很多开源工具的 README，是被当成说明书写的，实际上它是你流量最大的落地页。2025 年 9 月我们看一个开源监控工具的访问数据：README 页面月浏览 4.1 万次，官网首页 9000 次，差 4 倍多。但它 README 开头的三行是项目名、一行英文 slogan、一排徽章，没有一句说清这东西给谁用。
重写后的四步
第一步，开头 120 字说三件事：解决什么问题、和其他同类有什么不一样、谁适合用。这段要出现在折叠线以上，也就是前两三屏内。我们给那个监控工具写的开头是“替代 XX 的轻量指标采集器，单机可跑，内存占用 30MB 以内，适合 5 人以下团队”。改完之后 README 到官网的点击率从 1.2% 到 3.8%。
第二步，装完能跑。Quick Start 放在最前面，不超过 5 条命令，每条下面一行说明。开发者读 README 的平均停留时间只有 40 秒左右，第一屏给不出可执行的东西，他就走了。
第三步，截图或动图放在功能说明之后而不是之前。很多人把大图放第一屏，手机上看要滑三屏才见到字。GitHub 的移动端流量比很多人想的高，我们看过的几个 repo，移动端占三到四成。
第四步，结尾放“下一步”。文档链接、示例仓库、Discord 或微信群入口，三个就够。
README 的关键词怎么放
GitHub 页面在 Google 里权重很高，品牌词和项目名搜索时经常排官网前面。所以要覆盖两类词：项目名和它的变体（大小写、连字符、中文译名），以及品类的英文词。
具体位置：仓库描述（About 那一栏）、README 第一段、首个二级标题。这三个地方搜索引擎都会读。别在 README 里堆关键词，GitHub 的 Markdown 渲染出来是纯文本，堆了很难看，开发者一眼就看穿。
一个反常识的点
Star 数不直接影响搜索排名，但影响点击率。我们对比过两个功能接近的 repo，一个 18k star，一个 3k star，在同一个搜索词下前者点击率是后者两倍多。所以 README 里的 star 徽章、下载量徽章有用，但它们的作用在“说服”，不在“排名”。
另外，repo 的 topics 标签别空着。GitHub 的 topic 页本身有搜索流量，标签选对了能带来站内推荐流量。我们一般建议 6 到 10 个，覆盖语言、场景、品类。
什么时候该另开一个文档站
README 超过 4000 字就该拆了。GitHub 的阅读体验不适合长文档，锚点导航在移动端很难用。拆的时候 README 保留快速开始和核心概念，详细内容放文档站，README 里每个功能段落结尾给一条链接。
改 README 的投入产出比很高，一两天工作量，能影响接下来一整年的流量入口。这是我们给开源项目做的第一件事，通常比写博客早。
元析智能
为软件公司做 SEO 和 GEO 优化