项目没人愿意看说明，按这个 README 模板把使用门槛降下来

有个小工具丢到 GitHub 上，半个月零 star。后来翻了翻自己的 README，发现上来就是一长段设计理念，安装命令藏在第三段，连个能直接复制跑起来的例子都没有。换成任何路人，看两眼就关了。重写了一版 README 之后， clone 和 issue 明显多了。README 不决定项目好坏，但决定别人愿不愿意花那三分钟试一下。

一、README 的黄金结构

不用每次从零想，照这个顺序写基本不会错：

顺序很重要：把"装"和"跑"放在最前面，理念和架构往后放。大多数人打开 README 是为了用，不是来听你讲设计哲学。

二、最小示例要能"复制即跑"

这是最关键也最常被忽略的一段。好的示例长这样：

# 安装
npm install -g my-cli

# 一行跑通：把当前目录的 markdown 转成 html
my-cli build ./docs -o ./public

注意它满足三点：命令完整可复制、带输入和输出、不依赖读者的隐式知识。坏的示例是"调用 run() 方法即可"——run 什么？传什么参？读者得翻源码才知道，门槛一下就上去了。

三、配置和贡献别混在一起

项目稍大一点就会有配置项，建议单独列一节，用表格把参数名、默认值、含义写清：

| 参数        | 默认值   | 说明                 |
|------------|---------|----------------------|
| --port     | 8080    | 监听端口             |
| --watch    | false   | 文件变更自动重建     |
| --theme    | default | 主题名，见 themes/   |

贡献指南单独一节，告诉别人怎么本地起开发环境、测试命令是什么、PR 要过哪些 check。哪怕就写"fork 后改完提 PR，跑 npm test 通过即可"，也比没有强——很多人想帮忙但不知道从哪下手。

四、几个劝退写法要避开

• 开头先讲架构图和大段背景：路人只想先用起来，背景留到文档里。
• 示例代码有省略号 // 此处省略初始化：复制下来跑不通，直接劝退。
• 中英文混着没标点：读着累，显得不认真。
• 许可协议不写：别人不敢用，怕侵权。

构建状态接 CI、版本读 npm、协议读 LICENSE 文件，几行配置就上去了，能让项目一眼显得"正经"。

小结

README 写得好不好，决定别人愿不愿意花三分钟试你的项目。套用"标题定位 → 安装 → 最小可跑示例 → 配置 → 贡献 → 许可证"这个结构，把装和跑往前放、理念和架构往后放；最小示例一定要"复制即跑"，别留省略号逼人翻源码；配置项用表格列清参数默认值，贡献指南哪怕一句话也胜过没有。避开"开头先讲架构、示例带省略、无协议"这几种劝退写法，star 和 issue 自然会比之前多。