仓库首页不是给你自己看的说明书，是陌生人在三十秒内判断「要不要继续」的面试。
一、仓库不是文档，是入口
以下情境为教学假设，人物、引语和数字不代表经核实的真实案例。
一位开发者把自己产品的客户端代码开源了。仓库有 800 个 star，README 写着「本项目使用 TypeScript 与 React 开发，运行方式见 docs 目录」。三个月里，从仓库跳到产品页的访问不到 20 次，付费用户 0。
800 个 star 和 20 次访问之间的落差，来自一个简单的事实：star 是收藏，不是使用。 收藏的人可能只是想以后看看，而 README 没有回答「这跟我有什么关系」。
一个能带来访问的仓库，需要把「我做了什么」翻译成「你能用它做什么」。
二、README 的六段结构
| 段 | 内容 | 长度 | 常见错误 |
|---|---|---|---|
| 一句话 | 这是什么，给谁用 | 一行 | 写成技术栈介绍 |
| 效果 | 一张图或一段动图 | 一张 | 放 logo |
| 快速开始 | 一条命令跑起来 | 三行以内 | 先讲架构 |
| 用法 | 两三个真实场景 | 每个三行 | 罗列全部参数 |
| 限制 | 不支持什么 | 三条以内 | 完全不写 |
| 链接 | 文档、产品页、反馈入口 | 三条以内 | 放十个徽章 |
GitHub 官方文档对 README 的定位是「让别人了解你的项目能做什么、怎么用、怎么贡献」，这一句话本身就说明了顺序：先能做什么，再怎么用，最后才是贡献。
2.1 一句话的写法
「一个用 TypeScript 写的跨平台剪贴板管理器」是技术描述；「在十个窗口之间找回刚才复制的那段话」是用途描述。前者让人知道你用了什么，后者让人知道自己需不需要。
三、一条命令能跑起来
判断一个仓库是否会被真正使用，一条经验足够：从陌生人打开仓库，到看见东西运行，中间隔了几步。
| 步数 | 典型形态 | 实际完成率 |
|---|---|---|
| 1 步 | 复制一条命令 | 最高 |
| 2–3 步 | 安装依赖 + 启动 | 中等 |
| 4 步以上 | 配置环境、申请密钥、建数据库 | 很低 |
「配置环境、申请密钥」这类前置条件，是开发者工具流失的主要原因。可行的降级方案：
- 提供不依赖任何密钥的本地演示模式。
- 提供一个可直接运行的示例数据。
- 提供容器化的一键启动，而不是让用户装五个依赖。
这三件事都不难，但需要你在发布前真的用一台干净机器走过一遍。
四、示例与截图
示例的价值高于文档。一个能直接运行的例子，胜过十页参数说明。
| 内容 | 作用 | 优先级 |
|---|---|---|
| 最小可运行示例 | 证明能跑 | 最高 |
| 一个真实场景示例 | 证明有用 | 高 |
| 截图或动图 | 证明长什么样 | 高 |
| 完整文档站 | 证明可维护 | 中 |
| 架构说明 | 吸引贡献者 | 低 |
截图要展示结果，不要展示界面元素。读者想看的不是「你的窗口有几个按钮」，而是「做完之后是什么样」。
五、issue 回复即获客
仓库的 issue 区是公开的，任何搜索这个问题的人都能看到。这意味着一次认真回复，会被后来的人反复读到。
| 回复类型 | 效果 |
|---|---|
| 「请看文档」 | 关闭问题，不产生任何后续 |
| 直接给可运行的代码 | 被搜索到，带来访问 |
| 说明限制并给出替代方案 | 建立可信度 |
| 记录成文档 | 长期资产 |
把高频问题整理进文档，是仓库运营里投入产出最高的一件事：写一次，省下未来几十次重复回答，同时增加了一个可被搜索的页面。
六、收录：精选列表与目录
开源项目有一个天然的分发结构：各类精选列表与开发工具目录。
| 类型 | 收录方式 | 维护 |
|---|---|---|
| 精选列表（awesome 类） | 提交 pull request | 一次性 |
| 开发工具目录站 | 提交表单 | 一次性 |
| 包管理器与插件市场 | 发布包 | 随版本更新 |
| 同类项目对比页 | 联系维护者 | 一次性 |
提交时最重要的一条：你的项目必须真的属于那个分类。 塞进不相关的列表，会被维护者拒绝，也会带来错误的访问。
七、open core 的最小边界
很多独立开发者会问：开源了还怎么收费。最小可行的边界只有三条：
| 开放 | 收费 |
|---|---|
| 客户端与核心逻辑 | 托管服务与同步 |
| 单机使用 | 团队协作与权限 |
| 基础功能 | 批量、自动化与集成 |
这条边界的判断标准不是「哪个值钱」，而是**「哪部分用户自己维护得起」**。用户能自己跑起来的，开源不会伤害收入；用户跑不起来的（服务器、同步、合规），才是收费点。
反过来，把用户完全能自己搞定的事情锁起来收费，通常会换来一个 fork 和一段差评。
八、复算
假设仓库在三个月内获得 500 个 star，从仓库跳到产品页的比例是 3%，注册率 20%：
访问 = 500 × 3% = 15
注册 = 15 × 20% = 3
三个月 3 个注册，看起来很少。但要看两件事：
- 这些注册的质量通常更高。 从代码仓库来的人已经看过实现，理解成本低。
- 仓库是累积资产。 第二年的 star 与访问继续存在，不需要重复投入。
issue 的成本也要算进去：假设一年 60 个 issue，平均每个回复 3 分钟，合计 3 小时；如果其中 10 个被整理成文档，文档本身又成了搜索入口。
结论不是「开源值得做」，而是「开源只有在 README、示例、回复三件事都做到位时才值得做」。 只开源不维护，得到的是一堆 star 和零转化。
九、行动清单与复算验收
- README 六段齐全，第一行是用途不是技术栈。
- 在一台干净机器上，从零走到运行，记录步数并压到三步以内。
- 提供至少一个最小可运行示例和一个真实场景示例。
- 把三个高频问题写成文档。
- 提交到两个真正相关的精选列表，不广撒网。
验收标准：让一个不认识你的人只看 README，能说出这个项目解决什么问题、怎么跑起来、有什么限制。 三问有一问答不上，就还没写完。
使用边界与实操验收
开源不等于免费，也不等于必须接受所有贡献。本文不讨论许可证选择与社区治理，那些属于另一类问题；本文只讨论「仓库如何带来访问」。
验收以「陌生人能否独立跑起来」为准，不以 star 数为准。star 是结果，不是指标。
关键参考与核验范围
本文的结构建议与复算均为教学演示。核验日期：2026-10-23。
- About the repository README file - GitHub Docs ：GitHub 对 README 的定位与用途说明，可作为结构参考，不代表必须遵循的格式。
- 中华人民共和国个人信息保护法 ：仓库中若包含示例数据、遥测或用户提交内容，需按可识别性与最小必要原则处理。
各精选列表与目录站的收录标准由维护者自行决定，本文不附具体列表链接；提交前请阅读该列表当日的贡献说明。
系列导航
- 上一篇：搜索入口：问题页、模板页与对比页
- 下一篇：从落地页到第一个动作
- 回到目录：一个人让产品被看见：十条获客路径
- 相关阅读：独立开发者的平台寄生
继续阅读
探索更多技术文章
浏览归档，发现更多关于系统设计、工具链和工程实践的内容。