开源项目 README 自查清单：8 个最容易被忽略的点

README 是绝大多数人接触一个开源项目的第一站。写得清楚，别人愿意多停留几分钟；写得含糊，再好的代码也可能被划走。下面这 8 点，是我看过的项目里最常缺失的部分。

1. 一句话说清项目是什么

开头第一段就要回答：它解决什么问题、面向谁。避免上来就铺技术栈名词。

2. 提供一个能跑起来的最短路径

把“5 分钟上手”单独成节，命令可以直接复制。环境要求（版本、依赖）写在前面，而不是藏在附录里。

3. 说明前置条件

需要哪些账号、密钥、外部服务，提前列出来。很多新手卡住的地方不是代码，而是没意识到要先申请某个 key。

4. 给一个最小可运行示例

示例要能独立运行，最好带上预期输出。读者看到输出，才会相信自己的环境是对的。

5. 常见问题单独一节

把被反复问到的问题沉淀下来，能显著减少 Issue 数量。可以让读者先自查，再来提问。

6. 写清楚如何贡献

分支规范、提交信息格式、测试怎么跑、Issue 模板在哪，都值得写一句。降低贡献门槛，也是维护自己的时间。

7. 明确许可证

许可证决定了别人能不能在公司项目里用。缺这一节，很多团队会直接放弃。

8. 保持目录结构清晰

长 README 加一个目录，方便跳转。截图和架构图放在合适的位置，不要全部堆在开头。

自查之后

写完可以请一个没用过项目的人照着 README 走一遍，记录他卡住的每一步。那份记录，往往比任何写作技巧都更有价值。