根本原因是当前目录不在GOPATH/src下且未显式指定模块路径；实操应创建子目录后运行go mod init example.com/myapi，模块名需含点号、避免下划线或数字开头。
Go 1.21+ 安装后 go mod init 报错 “cannot determine module path”
根本原因不是 Go 没装好，而是当前目录不在 GOPATH/src 下、又没显式指定模块路径。Go 1.16+ 默认启用 module 模式，go mod init 需要一个合法的模块名（通常为项目 URL 或有意义的标识符）。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 不要在空目录或桌面根目录直接运行
go mod init，先创建项目子目录，例如mkdir myapi && cd myapi - 执行
go mod init example.com/myapi—— 模块名不必真实可访问，但需符合域名格式（含点号），避免用下划线或纯数字开头 - 若已有代码且依赖本地包，确保所有
import路径与go.mod中的 module 名前缀一致，否则编译时会报import cycle或cannot find module
用 swag init 生成 docs 时提示 “failed to parse Go source files”
Swagger 注释本身没问题，但 swag 默认只扫描当前目录及子目录下的 *.go 文件，且要求这些文件属于同一个 Go module；如果项目含多个 main 包、或有未 import 的工具文件（如 mocks/），容易触发解析失败。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 确认已安装
swagCLI：go install github.com/swaggo/swag/cmd/swag@latest（注意：不是go get，后者在 Go 1.21+ 已弃用） - 在
go.mod所在目录执行swag init -g cmd/myapp/main.go，显式指定入口文件，避免误扫无关目录 - 给 handler 函数加 Swagger 注释时，必须包含
// @Summary和// @Success，缺一不可，否则该接口不会出现在生成的docs/swagger.json中 - 避免在注释中写中文引号、全角符号或未闭合的
/* */块，swag解析器对语法错误非常敏感
启动服务后访问 /swagger/index.html 显示 404
不是路由没配，而是 swag 生成的静态资源（docs/ 目录）没被 Web 框架正确挂载。很多教程直接复制粘贴示例，却忽略了不同框架的静态文件注册方式差异。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 用
net/http原生启动时，必须手动注册：http.Handle("/swagger/", http.StripPrefix("/swagger/", http.FileServer(http.Dir("./docs")))) - 用 Gin 时，别漏掉
gin.DisableConsoleColor()之后的r.StaticFile("/swagger/index.html", "./docs/index.html")和r.Static("/swagger/doc.json", "./docs/doc.json")—— 单靠r.StaticFS容易因路径映射不匹配导致 404 - 生成文档后检查
docs/下是否存在index.html、doc.json、favicon-16x16.png等关键文件，缺失说明swag init执行异常，应重试并查看终端输出的 warning
修改接口签名后 Swagger 页面没更新
不是缓存问题，是开发者忘了重新运行 swag init。Swagger 文档是静态生成的，和 Go 编译过程完全解耦，改了 @Param 或返回结构体字段后，不重生成，页面永远显示旧内容。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 把
swag init -g cmd/myapp/main.go加进 Makefile 或 pre-commit hook，避免人工遗漏 - CI 流程中，在构建镜像前加入
swag init步骤，并校验docs/doc.json是否有变更，防止文档与代码脱节 - 如果使用 VS Code，可配置任务：在
.vscode/tasks.json中定义一个快捷命令，绑定到Ctrl+Shift+P → Run Task → swag-init
最常被跳过的一步是验证 docs/doc.json 是否能被浏览器直接打开并解析为有效 JSON —— 很多“页面空白”问题其实源于生成的 JSON 格式错误，但开发者直接去查服务器日志，反而绕远路。
