Go 1.19 起支持在文档注释中使用 [Link Text]: URL 语法自定义链接文字，而此前版本（≤1.18）仅支持自动识别 URL 和少数预设模式（如 RFC 编号），无法实现任意链接文本定制。
go 1.19 起支持在文档注释中使用 `[link text]: url` 语法自定义链接文字，而此前版本（≤1.18）仅支持自动识别 url 和少数预设模式（如 rfc 编号），无法实现任意链接文字定制。
在 Go 的文档注释（即 // 或 /* */ 中的注释块）中，Godoc 默认会将纯 URL（如 https://example.com）自动转换为可点击的 HTML 链接，且链接文字即为完整 URL。这种“所见即所得”的方式简洁但缺乏灵活性——例如，你可能希望显示更语义化的文字，如“查看官方设计文档”，而非一长串 URL。
✅ Go 1.19 及更高版本：支持自定义链接文字
从 Go 1.19 开始，Godoc 引入了类 Markdown 的参考式链接语法：
// Package example demonstrates custom doc links. // // See [Go Documentation Guidelines] for best practices. // // [Go Documentation Guidelines]: https://go.dev/doc/comment package example
在此示例中，[Go Documentation Guidelines] 作为链接锚文本，其实际跳转目标由下一行的 [Go Documentation Guidelines]: https://go.dev/doc/comment 定义。该定义必须独占一行，且链接文本需完全一致（区分大小写与空格）。多个链接可并列定义，Godoc 会自动解析并渲染为 <a href="...">Go Documentation Guidelines</a>。
⚠️ 注意事项：
- 链接定义不能嵌套在段落中，必须位于注释块内独立行；
- 链接文本中不可包含换行、制表符或未闭合的方括号；
- 定义与引用需在同一注释块内（不跨函数或类型声明）；
- 不支持内联式链接（如
[文本](url)），仅支持参考式（[文本]: url）； - 该特性仅被
godoc工具（含go docCLI 和pkg.go.dev）解析，部分 IDE 插件可能尚未支持实时预览。
❌ Go 1.18 及更早版本：无原生支持
在旧版本中，Godoc 仅对两类文本做智能链接化：
- 形如
https://...、http://...、ftp://...的完整 URL； - 特定前缀模式，如
RFC 2616、CL 123456、issue #789等（会映射到对应规范或 issue 页面）。
若需兼容旧版本，唯一变通方式是：在注释中先写语义化说明（如 “详见 RFC 7540”），再另起一行写出 URL，并依赖读者手动复制——但这牺牲了可访问性与用户体验。
总结
推荐升级至 Go 1.19+ 并采用 [Text]: URL 语法统一管理文档链接。它既保持注释的可读性，又提升生成文档的专业性。同时，建议将常用链接定义集中置于包级注释顶部，便于维护与复用。
