Go项目README必须包含4个硬性模块：顶部命令式安装语句、最小可运行示例（含package main和正确import路径）、明确Go版本兼容性（如go 1.21+）、CLI与API分界线；同时需确保import路径与GitHub URL一致、链接全用pkg.go.dev、go.mod末尾加keywords注释、统一用“Go”而非“Golang”、必加Go Report Card和pkg.go.dev徽章。
Go 项目在 GitHub 上“成功”的核心指标不是代码多漂亮，而是别人能不能 3 秒内看懂它能干什么、值不值得点 Star、敢不敢用在生产环境。这几乎全靠 README.md 驱动——它不是文档附属品，是 Go 项目的门面+说明书+SEO 入口。
Go 项目 README 必须包含的 4 个硬性模块
缺任何一个，新用户大概率划走。这不是风格问题，是 Go 社区的默认预期：
-
顶部一行命令式安装语句：比如
go install github.com/username/project@latest，不能只写go get（已弃用）或模糊的“使用 go build” -
最小可运行示例（含完整 import 路径）：必须带
package main和func main()，且 import 的包名要和实际 module path 一致（比如import "github.com/username/project/v2"） -
明确标注 Go 版本兼容性：不是“支持 Go 1.x”，而是具体写
go 1.21+（放在go.mod第一行的那条），并说明是否依赖embed、generics等特性 -
清晰的 CLI / API 分界线：如果项目同时提供命令行工具和库函数，必须用二级标题分开，且 CLI 示例用
$提示符，API 示例用//注释风格代码块
为什么 go.dev 收录失败？检查这 3 处链接一致性
go.dev 是 Go 官方文档索引源，但它的爬虫极度依赖链接结构。常见失败不是代码问题，而是 README 里藏了“幽灵路径”：
-
import语句里的路径必须和 GitHub 仓库 URL 完全匹配（包括大小写、v2后缀、是否带.git结尾） - 所有
godoc.org或旧版链接必须替换成pkg.go.dev，否则跳转 404 会拖累索引权重 - README 中若引用内部子模块（如
github.com/username/project/internal/xxx），go.dev不索引这些路径——确保主模块路径（go.mod里module声明的那行）被至少一处示例显式 import
GitHub 搜索排名低？把关键词塞进前 100 字 + go.mod 文件
GitHub 搜索不看全文，重点抓取 README.md 开头段落 + go.mod 内容。SEO 优化必须同步改两处：
- README 开头 100 字内，自然出现 2–3 个核心词：比如
Go CLI tool、HTTP client library、zero-dependency，避免堆砌；不要写“这是一个用 Go 写的工具”，直接写“fastjson：零依赖 JSON 解析器，比encoding/json快 3×” -
go.mod文件末尾加注释行：// keywords: cli, json, parser, performance—— GitHub 会扫描这行并计入搜索权重 - 避免在 README 标题用“Golang”：GitHub 搜索对 “Go” 敏感，“Golang” 匹配度极低；所有地方统一用
Go
徽章（Badges）不是装饰，是 Go 生态信任信号
Go 开发者扫一眼 README，靠徽章快速判断项目是否“靠谱”。无效徽章反而降低可信度：
- 必加
Go Report Card：链接形如https://goreportcard.com/badge/github.com/username/project，它检测gofmt、golint（或revive）、测试覆盖率 —— 如果分数低于 B，先修再放 - 用
pkg.go.dev徽章代替godoc：格式为，点击直达官方文档页 - CI 徽章必须指向真实构建记录：比如 GitHub Actions 的 badge 要带
?branch=main参数，且 workflow 文件里明确用了go test -v ./...，否则显示“unknown”等于自曝未测试
最容易被忽略的是：Go 模块路径一旦发布就不可更改，而 README 里每一处 import 示例、每一条安装命令、每一个徽章链接，都必须和这个路径咬死。错一个，新人第一分钟就会卡住——不是你的代码难，是门没开对。
