1.6 链接与图片

1.6 链接与图片

链接是方括号加圆括号，图片只比链接多一个感叹号。这一节练两种写法（行内式与引用式）、标题参数、以及大量出现的"图挂了/链接没生效"的排查思路。

跟着敲：两种链接

行内式，最常用：

详见[官方文档](https://example.com/docs)的配置章节。
​

引用式，把地址抽到文档任意位置集中管理：

详见[官方文档][docs]的配置章节。

[docs]: https://example.com/docs
​

两种渲染结果一样。我的取舍：链接少于十个用行内式（可读性好，一眼看到去向）；同一地址反复引用、或长文档要统一管理链接时用引用式（改一处全生效）。引用定义可以堆在文末，不占正文的阅读流。

链接还可以带"悬停提示"，写在圆括号里引号中：

[官方文档](https://example.com/docs "打开配置手册")
​

图片：加一个感叹号

![架构图](https://example.com/img/arch.png)
![本地图](images/arch.png)
​

方括号里是替代文本——图挂掉时显示它，读屏软件读它，搜索引擎也读它。别偷懒写成 ![]()，一行替代文本是文档质量的基本线。相对路径引用（如 images/xxx.png）要求图片和文档一起部署，平台型产品通常有自己的图床机制。

⚠️ 常见坑：图片语法三件套 ! [ ] ( ) 一个都不能少、不能加空格在 ]( 之间。链接变纯文字了，九成是方括号和圆括号之间多了空格，或者用了中文全角括号。

自动链接与锚点

裸网址在 GFM 里会自动变链接：

https://example.com 自动成为链接（GFM）
​

文档内部跳转靠"标题锚点"——渲染器通常把标题转成锚点，链接写 #标题小写连字符 形式。但锚点规则各方言不一致（中文标题尤其如此），跨平台文档尽量少依赖页内锚点，用"详见第 4 章"这类文字导航更稳。

一图看懂四种写法的结构差异

排查清单：链接/图片没生效

按命中率排序：

1. ]( 之间混入空格，或用了全角括号 （）。
2. 图片少了感叹号——渲染成了可点击的文字链接。
3. 圆括号内网址含空格或中文，未编码。
4. 相对路径的基准目录和渲染环境不一致（本地预览正常、线上挂掉）。

本节要点回顾

• 行内式短平快，引用式适合集中管理；悬停提示写在引号里。
• 图片 = ! + 链接结构，替代文本永远要写。
• 锚点方言差异大，跨平台文档用文字导航代替页内跳转。
• 排查顺序：空格/全角 → 感叹号 → 网址编码 → 路径基准。

链接的长期维护成本

链接写起来一行，麻烦都在后面。第一个坑是裸链深度链接：直接链到对方页面的具体段落（URL 里带一长串锚点或参数），对方改版后这种链接最先死。长寿命文档优先链到对方文档的入口页，配合一句"在站内搜索某关键词"的指引，牺牲一点直达性换数年的存活率。第二个坑是链接文字无信息量："点击这里""详见此链接"让读者无法预判去向，扫读时这些链接等于噪声；链接文字应当本身就是目的地描述——"详见官方部署手册"胜过"详见这里"一百倍。审阅文档时看到连续几个 here 链接，基本可以判定作者没站在读者角度收尾。

图片的维护成本更高，纪律也更多。图片内容含文字时，文字会随图片过期——版本号、界面截图、价格数字，这类图是文档里腐烂最快的部件。能写的用文字写（版本号、命令输出），必须截图的（界面操作）在文件名里带版本信息，方便日后批量定位"哪些截图属于已淘汰版本"。图片尺寸也值得约定：正文图统一宽度（比如 800 像素左右），插入时不要依赖渲染器缩放巨大原图——仓库体积和加载速度都是真实成本。团队如果用相对路径管理图片，建议按章节建目录（images/ch01/），文件名对应章节与小节，图挂掉时按路径就能反查出该修哪一节。

相对路径的基准问题：一次讲透

相对路径"本地好好的、线上挂了"的根因是解析基准不同：编辑器预览以文件所在目录为基准，静态站点以最终 URL 路径为基准，而站点的 URL 结构往往不等于目录结构。同一句 images/arch.png，在 docs/intro.md 里本地能渲染，部署后页面 URL 是 /docs/intro/，相对路径就指向了 /docs/intro/images/arch.png——一个不存在的位置。三种解决路线对比：

方案 A：站点根路径     /assets/images/arch.png
方案 B：仓库相对路径   ../../assets/images/arch.png
方案 C：构建期重写     源码写 images/arch.png，构建器统一补前缀
​

方案 A 简单但源码离开站点就失效（GitHub 网页预览看不到图）；方案 B 到处可用但层级一变全断；方案 C 最稳，mkdocs、VitePress 等主流工具都内置支持。选型的判断标准就一条：这份文档是否有"离开构建环境的第二读者"——有，避开根路径写法。

图片的替代文本写法也有高低之分。最低标准是描述内容（"架构图"），合格标准是描述信息（"三层架构：网关、服务集群、数据库"），两者工作量只差一句话，但读屏用户与图挂掉时的体验差距巨大。替代文本不要以"图片："开头（读屏软件本来就会 announce 这是图），也不要复述图里每一个细节——那是长描述该干的事，个别平台支持 title 参数或专门的 figure 结构承载。最后一条实用纪律：装饰性图片给空替代文本（![](https://aiknowledge.cn/images/Markdown/spacer.png)），让读屏软件直接跳过，反而比硬塞一句"分隔装饰"更友好。

基础语法到此收齐。下一章让信息"立起来"——表格、任务列表、脚注。

链接检查的半自动办法

长文档的链接失效无法靠肉眼维护，值得建立半自动检查流程。仓库型文档最简单的做法是在 CI 里加一步链接检查工具（lychee、markdown-link-check 都常用），扫描全部 Markdown、报告死链与重定向，输出一份按文件分组的清单。本地写作时，VS Code 的 Markdown 链接检查扩展能在保存时给失效的相对路径直接画波浪线，图挂掉的问题在编辑期就暴露。内网地址、需要登录的链接要维护一份忽略清单交给检查工具，避免每次报告被噪声填满。链接检查的合理频率是随发布触发，而不是每天——死链是随对方改版产生的，发布前拦截就够了。