go doc 默认不自动更新缓存，修改本地 Go 源文件注释后仍显示旧文档；需结合 -u 标志（针对未安装包）或改用 godoc 工具（已弃用但功能更全），而现代推荐方案是使用 go doc 配合模块缓存刷新或直接启用本地 HTTP 文档服务器。
`go doc` 默认不自动更新缓存，修改本地 go 源文件注释后仍显示旧文档；需结合 `-u` 标志（针对未安装包）或改用 `godoc` 工具（已弃用但功能更全），而现代推荐方案是使用 `go doc` 配合模块缓存刷新或直接启用本地 http 文档服务器。
在 Go 1.21+ 中，go doc 已成为官方推荐的命令行文档查看工具（取代了已归档的 godoc），但它不会主动监听文件系统变化，也不维护独立缓存——它始终基于当前模块环境（go.mod）、GOROOT 和 GOPATH 下已构建/安装的包信息实时生成文档。因此，“文档未更新”通常源于以下原因之一：
✅ 正确做法：确保源码变更已生效
-
go doc直接读取.go源文件（非编译产物），无需重新构建或安装，但要求：- 当前工作目录在模块根目录（含
go.mod），或通过-workdir指定； - 被查文档的包路径可解析（如
go doc mymodule/pkg）； - 文件保存后立即生效（无缓存延迟）。
- 当前工作目录在模块根目录（含
示例：
# 假设你修改了 ./pkg/example.go 中的函数注释 $ go doc mymodule/pkg.MyFunc # 立即显示最新注释（只要模块路径正确）
⚠️ 常见误区与解决方案
❌ 错误：在
$GOROOT/src或全局GOPATH/src外修改代码，却用go doc std/fmt类方式查询 —— 此时查的是标准库原始文档。
✅ 正确：对本地模块使用相对/模块路径：go doc ./pkg或go doc mymodule/pkg。❌ 错误：使用
go doc -u试图“刷新缓存”——-u仅表示“显示未导出标识符”，不触发任何缓存清理或重载逻辑。
✅ 无需-u：公开文档默认可见；若需查看私有成员，才加-u，且仍以源文件为准。
? 终极验证方法：启动本地文档服务器
当需要类 IDE 的实时预览体验，推荐使用内置的 go doc HTTP 模式（Go 1.22+ 原生支持）：
# 启动本地文档服务（自动监听文件变更，热更新界面） $ go doc -http=:6060 # 浏览器打开 http://localhost:6060/pkg/your-module/
该服务会实时读取磁盘文件，修改保存后刷新页面即可看到最新文档，无需手动干预。
? 总结
-
go doc本身无持久缓存，所谓“未更新”本质是路径错误或作用域误解； - 优先检查模块路径、工作目录和包导入路径是否一致；
- 避免依赖已归档的
godoc工具（自 Go 1.13 起不再随安装包分发）； - 日常开发推荐
go doc <package></package>直查 +go doc -http本地服务双模式，兼顾效率与可视化。
