pkg.go.dev 收录需满足：仓库公开可访问、存在 go.mod 文件、module 声明与仓库地址完全一致、有带 v 前缀的 tag（如 v0.1.0），且能成功 go get；文档显示依赖紧邻声明的规范 go 注释；latest 指向 main 分支 head 或最高合法 tag。
Go 包怎么才能被 pkg.go.dev 收录
pkg.go.dev 不是手动提交的平台，它只抓取公开可访问的 Git 仓库（GitHub、GitLab、Bitbucket 等），且必须满足两个硬性条件：go.mod 文件存在 + 仓库根路径能 go get 成功。
常见错误现象：go get example.com/mylib 报 unknown revision 或 no matching versions，说明 pkg.go.dev 根本不会尝试抓取——它连最基本的模块解析都失败了。
- 确保
go.mod中module声明与仓库地址完全一致（比如 GitHub 仓库是github.com/you/repo，module就得是这个，不能写成example.com/repo） - 首次推送前先本地运行
go mod tidy，再git tag v0.1.0（带v前缀），然后git push --tags - 私有仓库、子目录模块（如
github.com/you/repo/sub）、未打 tag 的 commit 都不会被索引
为什么文档没显示函数说明或参数注释
pkg.go.dev 显示的文档，直接来自源码中的 Go 注释（不是 // 行注释，而是紧贴声明上方的块注释），且仅识别符合 Go 文档规范的格式。
使用场景：你写了 // Add returns sum of a and b，但 pkg.go.dev 里函数下面空空如也——因为这不是合法的文档注释。
立即学习“go语言免费学习笔记（深入）”；
- 函数/类型/变量的文档注释必须是紧邻其声明上方的
/* ... */或以//开头的连续多行，且首行要描述对象本身（例如// Add adds two integers.） - 参数和返回值不写在注释里也能生成文档，但想让它们出现在 pkg.go.dev 的“Parameters”或“Returns”区块，得用
// Parameters:或// Returns:这类标准标记（非必需，但推荐） - 注释里不要出现
@param、/** @return */这类 JSDoc 风格，Go 工具链不识别
go.dev 上版本显示为 “latest” 而不是具体 tag
这是 pkg.go.dev 的默认行为：只要仓库有 main（或 master）分支，且该分支 HEAD 能成功构建，就会把那个 commit 标为 latest。它不是 bug，是设计如此。
性能 / 兼容性影响：用户执行 go get example.com/lib@latest 实际拉的是 main 分支最新 commit，不是最近 tag —— 这可能破坏语义化版本预期。
- 如果希望
@latest指向最新稳定版，就别往main推未经测试的代码；或者干脆删掉main分支，只维护带v前缀的 tag（pkg.go.dev 会自动选最高 tag 作为latest） -
go list -m -versions example.com/lib可确认哪些版本实际被识别；若输出为空，说明模块未被正确索引或 tag 格式非法（比如0.1.0缺少v） - 打 tag 后需等待几分钟到几小时（无通知），pkg.go.dev 才会刷新；手动触发无效
如何验证文档是否会被正确渲染
不用等 pkg.go.dev 抓取，本地就能预览效果，而且能暴露绝大多数格式问题。
实操建议：用 Go 自带的 godoc（已弃用）不行，要用 go doc CLI 或 VS Code 的 Go 插件实时提示，最可靠的是跑一次 go doc -all。
- 在模块根目录执行：
go doc -all > /dev/null，如果报错（如no documentation for package），说明注释位置或格式有问题 - 检查导出标识符（首字母大写）是否都有对应注释；未导出的函数即使有注释也不会出现在 pkg.go.dev
- 避免在注释中使用 Markdown 语法（如
**bold**或列表），pkg.go.dev 渲染器不支持，会原样显示甚至截断
最容易被忽略的是：模块名、tag 名、仓库地址三者必须严格一致，差一个字符，pkg.go.dev 就当它是另一个包——没有错误提示，只是永远不出现。
