godoc本地服务启动失败主因是端口冲突或工作目录不在gopath/src或模块根下；需确认路径、换端口或显式指定-goroot；注释须紧贴导出标识符且无空行；静态文档推荐golds。
godoc 本地服务启动失败：端口被占或找不到包
直接运行 godoc -http=:6060 却打不开 http://localhost:6060，大概率是端口冲突，或者当前工作目录不在 GOPATH/src 或 Go Modules 根下。godoc 不会自动扫描任意路径，它只认标准包路径结构。
- 先确认 GOPATH（
go env GOPATH），然后 cd 进入$GOPATH/src或你的模块根目录（含go.mod）再启动 - 换端口更省事：
godoc -http=:6061，避免和旧进程、VS Code 插件或其他 godoc 实例抢:6060 - Go 1.13+ 默认启用 module 模式，但
godoc命令本身不原生支持 go.work 或多模块 workspace，跨模块引用的文档可能缺失——这不是 bug，是设计限制 - 如果提示
no such package，检查包是否已go install过（尤其非 main 包），或尝试加-goroot显式指定 SDK 路径
注释没出现在 godoc 页面：格式和位置不对
godoc 只提取紧贴在声明前的「块注释」（/* ... */）或「行注释」（//），且必须与目标标识符之间**不能有空行**。导出标识符（首字母大写）才可见；未导出的函数/字段即使有注释也不会显示。
- 正确写法：
// ParseConfig 解析 YAML 配置文件，返回 Config 实例。<br>func ParseConfig(path string) (*Config, error) { ... } - 错误写法：在函数体里写
// TODO: 支持 JSON，或注释和函数中间隔了一行空行 - 结构体字段注释必须写在字段行上方，且字段名首字母大写才生效：
// Timeout 是请求超时时间（秒）<br>Timeout int `json:"timeout"`
- 包级注释要放在
package xxx上方，且整个包只能有一个包注释块（多个会被忽略）
生成静态 HTML 文档：替代 godoc 服务的轻量方案
godoc 服务适合开发中快速查，但交付或 CI 场景需要离线 HTML。官方 godoc 命令不支持静态导出，得靠第三方工具，docgen 或 golds 更可靠。
- 推荐
golds（Rust 写的，速度快，支持 Go 1.20+）：go install github.com/yuin/goldmark/cmd/golds@latest，然后golds -output docs/ ./... - 避免用过时的
godoc -html，它早已被移除（Go 1.14+ 不再支持） - 静态站点要注意相对路径：生成后打开
index.html必须用 HTTP Server（如python3 -m http.server），直接双击会因同源策略加载失败 - 如果项目用了
//go:embed或//go:generate，静态生成器不一定能解析这些指令，文档里不会体现生成逻辑
中文注释乱码或排版错乱
godoc 对 UTF-8 支持没问题，但换行、缩进、特殊符号容易让渲染失真。重点不是编码，而是 Markdown 兼容性和空白处理。
立即学习“go语言免费学习笔记（深入）”；
- 避免在注释里用制表符（
\t）缩进，全用空格；godoc 渲染器对 tab 处理不稳定 - 中文标点后别多加空格，比如
。（句号+空格）可能导致后续文字缩进异常 - 要写代码块，用四个空格缩进（不是
```），例如：// 示例：<br>// cfg := Config{Timeout: 30}<br>// err := cfg.Validate() - 注释里不要出现未闭合的
或 <code>>，godoc 会误判为 HTML 标签并过滤掉部分内容
真正麻烦的是跨包类型引用——比如 A 包文档里写了 *B.Type，但 B 包没被 godoc 加载，链接就 404。这没法靠单个命令解决，得统一管理依赖包的文档路径，或者接受局部缺失。
