Golang模块文档生成与pkgsite使用教程

pkg.go.dev 是 Go 官方自动化的模块文档托管平台，只需将符合规范的 Go 模块推送到公开 Git 仓库、确保 go.mod 路径与仓库 URL 一致、用语义化版本打 tag，并在源码中编写规范的纯文本注释（包级注释作简介、导出标识符上方注释作 API 说明、Example 函数作可运行示例），即可零配置、免构建地获得专业级结构化文档页面——无需运行任何生成工具、不依赖 CI、也不产生静态文件，真正实现“写好代码即拥有文档”的极简体验。

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 分支最新状态。

• 运行 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://pkg.go.dev/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 就会自动工作。

今天带大家了解了的相关知识，希望对你有所帮助；关于Golang的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~