pkgsite无法直接读取本地未发布模块，必须通过合法module path、本地代理和显式缓存三者配合；根本原因是它只识别go.mod声明的合法路径且依赖go list -m -json输出，不扫描文件系统。
pkgsite 不能直接读取本地未发布的 Go 模块，必须通过本地代理 + 显式缓存 + 合法 module path 三者配合才能生效。它不是 godoc 那种基于文件系统扫描的本地服务。
为什么 pkgsite 打开 localhost:8082 就报 “module not found”
根本原因在于 pkgsite 不解析当前目录或文件路径，它只认 go.mod 第一行声明的 module 路径，并且必须能被 go list -m -json 正确识别。
-
go.mod写的是module .或module myproj→ 非法路径，pkgsite直接跳过 - 模块路径含大写字母（如
MyProj）或下划线（my_proj）→ Go 工具链不认可，go mod download失败，pkgsite拉不到数据 - 没设
GOPROXY，pkgsite默认走https://proxy.golang.org，本地模块自然 404 - 没在项目根目录执行
go list -m -json，输出里没有"Path": "github.com/you/proj"字段 →pkgsite根本推导不出该模块存在
让 pkgsite 加载本地模块的最小可行步骤
绕过远程 fetch，用 goproxy 搭一个只服务本地模块的代理是最轻量方案。关键动作必须按顺序做：
- 确保项目根目录有合法
go.mod：例如module github.com/yourname/mylib（不能是相对路径或非法字符） - 启动本地代理：
goproxy -proxy=localhost:8081 -cache=/tmp/goproxy-cache - 设置环境变量：
export GOPROXY=http://localhost:8081,direct - 手动触发缓存：
go mod download github.com/yourname/mylib@latest（这步会把本地代码打临时 tag 并存进$GOCACHE/download） - 启动
pkgsite：pkgsite -http=:8082 -proxy=http://localhost:8081 - 浏览器访问：
http://localhost:8082/github.com/yourname/mylib（URL 路径必须和go.mod的module值完全一致）
改了代码后文档不更新？这是设计使然
pkgsite 不监听文件变更，也不重新解析源码。它展示的是 go mod download 缓存下来的那一版快照。每次修改代码后要刷新文档，必须重复执行：
-
go mod download github.com/yourname/mylib@latest（强制重缓存） - 或者更精确地用
go mod download github.com/yourname/mylib@v0.0.0-$(date -u +%Y%m%d%H%M%S)-$(git rev-parse --short=7 HEAD)打带时间戳+commit 的伪版本
如果你需要实时响应代码改动，godoc -http 或 go doc -http（Go 1.23+）才是更匹配的工具；pkgsite 的定位是“已发布模块的稳定文档视图”，不是开发过程中的活预览器。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
