pkg.go.dev 是 Go 官方推荐的模块文档托管服务，自动为公开 Git 仓库中满足 module 路径一致、符合注释规范、打有语义化版本 tag 等条件的 Go 模块生成结构化文档。
Go 官方推荐的模块文档托管服务是 pkg.go.dev，它会自动为公开的 Go 模块生成结构化文档页面。你不需要手动运行工具生成静态 HTML，但需确保模块满足特定条件，才能被 pkg.go.dev 正确索引和渲染。
模块必须是公开可访问的
pkg.go.dev 只抓取托管在公开 Git 仓库（如 GitHub、GitLab、Bitbucket）上的模块，且仓库地址需能被公网直接 clone。
- 私有仓库、本地路径（
file://）、或需认证才能访问的地址，不会被索引 - 确保
go.mod中的 module 路径与仓库 URL 一致，例如：module github.com/username/repo→ 对应https://github.com/username/repo - 若使用自定义域名（如
gitea.example.com/user/proj），需确保该域名可解析、端口开放、且支持git clone
代码需符合 Go 文档规范
pkg.go.dev 的文档内容完全来自源码中的注释，不是额外生成的文件。关键规则如下：
- 包级注释（紧贴
package xxx上方的块注释）会被作为包简介显示 - 导出标识符（首字母大写的函数、类型、变量、常量）上方的注释，会作为其文档展示
- 注释应为纯文本，不支持 Markdown 渲染（如
**加粗**或列表符号会被原样显示） - 示例函数（以
ExampleXXX命名，且无参数无返回值）会被自动提取并渲染为可运行示例
版本标签决定文档可见性
pkg.go.dev 默认只显示打了语义化版本 tag（如 v1.2.0、v2.0.0）的提交，不展示未打 tag 的 commit 或 main/master 分支最新状态。
立即学习“go语言免费学习笔记（深入）”；
- 运行
git tag v1.0.0 && git push origin v1.0.0后，通常数分钟内就会出现在 pkg.go.dev - 若模块有 v2+ 版本，需在
go.mod中体现：如module github.com/you/mod/v2，对应 tag 为v2.1.0 - 预发布版本（如
v1.0.0-beta.1）也会被索引，但默认不设为“最新稳定版”
验证与调试技巧
如果文档没出现或内容异常，可快速自查：
- 访问
https://www.php.cn/link/f642bc91378fbcd8ef4d89d644c91fe9/your-module-path，查看是否提示 “No documentation found” 或 “Module not found” - 用
go list -m -json your-module-path@latest检查模块元信息是否可解析 - 用
go doc -url your-module-path在本地模拟 pkg.go.dev 渲染效果（需 Go 1.21+） - 检查
go.mod是否含// indirect错误，或 replace 指向了本地路径（这会导致远程无法解析）
基本上就这些。没有额外命令、不用配置 CI、也不需要生成 .md 或 .html 文件——写好注释、打好 tag、推到公开仓库，pkg.go.dev 就会自动工作。
