逛 GitHub 时间长了你会发现，判断一个项目值不值得深入，根本不用先把它 clone 下来折腾。README 写得怎么样，基本就决定了这个项目的下限。一个连文档都写不清楚的项目，代码大概率也好不到哪去。

这篇就聊聊怎么读 README，三分钟判断项目靠不靠谱。

一个靠谱的 README 长什么样

先建立基准线。一个维护良好的项目，README 通常包含这几块：

一句话介绍 + 徽章。 开头用一两句话说清这是干什么的，下面挂几个徽章（构建状态、版本号、许可证）。徽章本身不重要，重要的是作者愿意把项目的"健康状态"亮出来。

安装和快速上手。 靠谱的项目一定有"三步跑起来"的说明。如果安装部分写得含糊其辞，或者默认你什么都懂，新手基本可以直接劝退了。

用法示例。 光讲概念不给例子，等于没讲。好的 README 会贴几个最常见的用法，复制粘贴就能跑。

贡献指南或指向 CONTRIBUTING 的链接。 有这一项，说明作者欢迎社区参与，项目是"活"的。

三分钟速判法：先看这五个地方

时间有限的话，按这个顺序扫一遍：

1. 最后更新时间。 页面右上角就能看到。README 三年没动、commit 停在两年前，但 Star 数很高——这种项目多半是"历史遗产"，能用但别指望有人维护。

2. Issue 区的处理情况。 点进 Issues 看看：作者回不回复？多久回复一次？堆了几百个无人理睬的 issue，说明维护者已经跑路或者顾不上。

3. 文档完整度。 只有两行简介加一句"coming soon"的，直接关。文档越细，作者对这个项目的投入度通常越高。

4. 有没有截图或演示。 工具类、界面类项目，连张截图都不放的，要么是作者懒，要么是东西拿不出手。反过来，有动图演示的一般都比较用心。

5. 许可证。 滑到最底部看一眼。有明确开源许可证（MIT、Apache、GPL 等）才算真正的开源项目。没有许可证的，法律上你其实没有使用授权，企业项目尤其要注意这点。

危险信号：看到这些可以直接关掉

  • README 只有一句话，剩下全是 TODO
  • 安装说明里让你"先看源码"
  • Issue 区全是"这个项目还维护吗"且无人回复
  • 宣称"吊打 XX"，但没有任何对比依据
  • 许可证一栏空着，却到处写"免费使用"

进阶：README 之外的两个验证动作

README 只能看门面，想再确认一下，做这两件事：

看 commit 历史。 点进 Commits，看看提交频率和最近一次提交时间。稳定、小步快走的提交记录是最健康的信号。一次性提交几万行代码然后沉寂两年的，要当心。

看真实的讨论。 翻几个 closed 的 issue，看作者解决问题的态度。一个愿意认真回复 issue、修 bug 的维护者，比 Star 数高但爱答不理的靠谱得多。

写在最后

读 README 本质上是在读作者的态度。文档用心，代码大概率也差不到哪去；文档敷衍，Star 再高也要打个问号。

之前写过一篇 《GitHub 新手第一课：从 Star 开始》，讲的是怎么用 Star 功能，那篇是从"用"的角度聊的。这篇是从"看"的角度聊的，一个看门面（README），一个看里子（维护状态），两套方法加起来，基本不会再踩坑。