go 1.13起godoc已移出标准工具链，需手动安装golang.org/x/tools/cmd/godoc@latest；启动服务需确保go111module=on、配置goproxy，并将$gobin加入$path；文档可见性依赖正确注释位置、导出标识及有效go.mod。
Go 1.13 起 godoc 命令已从标准工具链移除，必须手动安装才能启动本地文档服务；不装就直接执行 godoc -http=:6060 会报“command not found”。
godoc 命令找不到？先装再用
这是最常卡住的第一步。Go 官方从 1.13 开始把 godoc 移出 go 工具集，它现在属于 golang.org/x/tools 子模块。
- 确保启用了 Go modules：
go env -w GO111MODULE=on - 配置可用代理（国内环境必需）：
go env -w GOPROXY="https://goproxy.cn,direct" - 运行安装命令：
go install golang.org/x/tools/cmd/godoc@latest（注意：不是go get，go get在 Go 1.17+ 后已弃用） - 安装成功后，
godoc二进制会落在$GOBIN目录下（默认是$GOPATH/bin），确保该路径在$PATH中
启动本地文档服务：端口、根目录与同步行为
godoc -http=:6060 启动的是一个静态扫描型 Web 服务，它不会自动监听文件变化，也不会“实时同步”。所谓“同步”，其实是每次请求时重新解析源码 —— 所以你改完注释后，刷新页面就能看到更新，但不需要重启服务。
- 默认只索引
$GOROOT/src（标准库）和$GOPATH/src下的包；若想包含当前项目，需用-goroot显式指定根路径，例如：godoc -http=:6060 -goroot=. - 端口可任意换，比如
-http=:8080，但别选被占用的（如 macOS 上 6060 常被其他工具占） - 没有内置的“自动重载”或 “sync_minutes” 参数 —— 那是过时资料里的错误描述，
godoc本身不支持定时扫描，也不读配置文件 - 如果项目不在
GOPATH或GOROOT下，又不想改-goroot，更现代的做法是用go doc -http=:6060（Go 1.21+ 内置），但它只服务标准库和已安装模块，不扫本地未go mod init的裸目录
注释写法决定文档是否可见：紧贴、无空行、导出标识
Godoc 不是关键词提取器，它靠语法位置匹配注释。写错位置，注释就彻底消失。
- 包级注释必须紧贴
package xxx上一行，中间不能有空行；多文件包中，godoc按文件名排序合并所有包注释 - 函数/类型/变量注释必须紧贴其声明（
func/type/var）上一行，同样禁止空行隔开 - 只有首字母大写的标识符（即导出的）才会出现在文档中；
func helper()再详细注释也看不到 - 示例函数必须放在
_test.go文件里，函数名以Example开头（如ExampleQueue_Push），末尾加// Output:块，且输出必须严格匹配实际运行结果（go test会校验）
浏览器访问时看不到你的包？检查这三个路径条件
即使 godoc -http=:6060 -goroot=. 成功运行，http://localhost:6060/pkg/ 仍可能不显示你的包 —— 这和“是否能 import”强相关。
- 你的包目录必须含有效
go.mod文件（即已go mod init mypkg），否则godoc视为不可导入的匿名目录 - 包路径要能被解析：比如
go.mod里是module github.com/user/mypkg，那文档地址就是http://localhost:6060/pkg/github.com/user/mypkg/ - 若用
-goroot=.，当前目录必须是模块根（即含go.mod），且子目录结构要符合 Go 包路径逻辑（不能有非法字符、不能以数字开头等） - 浏览器打开首页后，别只盯着左侧导航栏 —— 有时你的包出现在 “Third Party” 分类下，或需要手动输入完整路径访问
真正容易被忽略的点是：godoc 的文档生成完全依赖 Go 的构建系统视角。它不关心你 IDE 里怎么组织文件，只认 go list 能识别的包。写完注释却看不到？先 go list ./... 看是否列出了你的包 —— 这比反复重启 godoc 有用得多。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
