Golang包文档工具，pkgsite本地使用教程

本文详解了如何绕过 pkgsite 默认仅支持已发布模块的限制，实现在本地高效查看未发布Go项目的完整文档——核心在于构建“本地goproxy + 合法module路径 + 手动缓存”闭环链路，同时厘清了常见报错（如“module not found”）的根本原因，并对比推荐了更轻量的替代方案（如go doc CLI或godoc服务），帮助开发者根据实际场景理性选择：追求美观跨链体验可配置pkgsite，专注快速迭代调试则优先选用原生工具链。

pkgsite 能不能直接看本地 Go 项目文档？

不能，pkgsite 默认只服务已发布到 proxy.golang.org 的模块，本地未发布的代码不会被自动索引。它不是 godoc 那种开箱即用的本地文档服务器。

想用 pkgsite 看自己写的包，必须让它的后端“认为”这个模块是可解析的——核心是伪造一个可用的模块路径，并让它能被 go list -m -json 和 go mod download 流程识别。

• 你的模块必须有 go.mod 文件，且 module 声明不能是伪路径（如 example.com/myproj 可以，./myproj 不行）
• 需要在本地启动 pkgsite 并配置为使用本地 Go proxy 缓存（而非直连官方 proxy）
• 首次访问前，得手动触发一次 go mod download，让模块进到本地 cache（$GOCACHE/download）里

怎么让 pkgsite 读到本地未发布的模块？

关键是绕过远程 fetch，改用本地 goproxy + pkgsite 组合。最轻量的做法是用 goproxy 搭一个只服务本地模块的代理，再让 pkgsite 从它拉数据。

实操步骤：

• 确保 GO111MODULE=on，且项目根目录有合法 go.mod（比如 module github.com/you/proj）
• 运行 goproxy -proxy=localhost:8081 -cache=/tmp/goproxy-cache（它会监听本地 8081）
• 设置环境变量：export GOPROXY=http://localhost:8081,direct
• 执行 go mod download github.com/you/proj@latest —— 这步会把本地模块打个临时 tag 并缓存进去
• 启动 pkgsite：pkgsite -http=:8082 -proxy=http://localhost:8081
• 浏览器打开 http://localhost:8082/github.com/you/proj

注意：pkgsite 不会实时监听文件变更，改了代码要重新 go mod download 才能刷新文档。

为什么 pkgsite 显示 “module not found” 却 go build 正常？

因为 pkgsite 查的是 module path（即 go.mod 第一行），不是文件路径。常见坑：

• go.mod 里写的是 module . 或 module myproj —— 这属于非法 module path，pkgsite 直接忽略
• 模块路径含大写字母或下划线（如 MyProj），Go 官方工具链不认可，pkgsite 也不会处理
• 本地没设 GOPROXY，pkgsite 默认去 proxy.golang.org 找，自然 404
• go list -m -json 在当前目录下执行失败（比如不在 module 根目录），pkgsite 就没法推导出有效路径

验证方法：在项目根目录运行 go list -m -json，输出里必须有非空的 Path 字段，且和浏览器访问的 URL 路径完全一致。

替代方案比硬刚 pkgsite 更省事？

如果只是临时查本地包结构、函数签名、注释，godoc（旧版）或 go doc CLI 更直接：

• go doc -http=:6060 启动本地服务，访问 http://localhost:6060/pkg/ —— 支持未发布模块，实时响应
• go doc github.com/you/proj 或 go doc github.com/you/proj.MyFunc 查具体项
• VS Code + Go 插件按 Ctrl+Click 跳转也能渲染大部分注释，无需额外服务

pkgsite 的优势在于 UI 和跨模块链接能力，但代价是强依赖模块发布流程。对纯本地开发来说，它不是默认最优解，而是特定部署场景下的选择。

真正卡住的往往是模块路径命名和 GOPROXY 链路是否闭环——这两点没对齐，后面所有步骤都白搭。

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