Go 官方 godoc 工具不支持在生成的 HTML 文档中嵌入本地或远程图片，这是其设计限制，无法通过注释语法或配置绕过。
go 官方 `godoc` 工具不支持在生成的 html 文档中嵌入本地或远程图片，这是其设计限制，无法通过注释语法或配置绕过。
虽然 Go 的文档注释（即 // 或 /* */ 中的纯文本块）支持基础格式化——如代码块（缩进 4 空格或围以 ``go</code>）、列表和链接——但**完全不解析 Markdown、HTML 标签或图像语法**（例如
或
✅ 正确做法（替代方案）：
-
使用文字描述+ASCII 图形：对简单结构（如数据流、调用关系），可用等宽字体绘制示意（如下）：
┌─────────┐ ┌──────────┐ │ Client │───▶│ Processor│ └─────────┘ └──────────┘ ▲ │ └──────────────┘ -
提供外部文档链接：在注释中添加指向托管在 GitHub Pages、DocuSaurus、Hugo 或 pkg.go.dev 自定义 README 的链接：
// See the architecture diagram at: https://example.com/docs/arch.png // Or interactive docs: https://example.com/docs/
⚠️ 注意事项：
- pkg.go.dev（Go 官方模块文档站点）同样基于 godoc 后端，也不支持图片；
- 第三方工具如 golds 或 docgen 可扩展支持 Markdown 和图片，但需自行部署，且不被 Go 生态默认集成；
- 若团队内部需富文档，建议将 godoc 作为 API 参考（保持简洁准确），另建独立文档站点（如 Docusaurus + Go code snippets）承载图表、教程与用例。
总之，godoc 的核心定位是轻量、可移植、纯文本优先的 API 文档工具。图像需求本质上超出了其设计边界——接受这一约束，并分层使用工具（godoc 保 API，外部系统承设计），才是符合 Go 工程哲学的务实选择。
