那些写在 README 里但没人做的事

1. README 的真实作用

不是介绍项目，是让人知道怎么开始、知道出问题时怎么办。

一个项目如果要交接给别的人，README 里必须有三样东西：怎么装、怎么跑、出错了找谁或者怎么查。缺一样，交接就会变成一次现场问询。

2. 必须有的四块

1. 这是什么，一句话说清

不要写成产品介绍，写清楚它解决什么问题、适合谁用。

一个用来把 CSV 转成指定格式的命令行工具，
适合需要在 Excel 之外快速处理结构化数据的场景。

2. 怎么跑起来

前置条件 + 两条命令。这块是最常出错的，因为文档写完之后环境就变了。

## 依赖
Node.js >= 18

## 运行
npm install
npm run dev        # 开发
npm run build      # 构建，产物在 dist/

注明版本要求，不写的话别人用 Node 14 跑出一个奇怪的报错，还要自己排查。

3. 目录结构

不用很详细，标出关键目录就行。新人接手时能快速知道东西在哪。

src/
  api/     接口请求
  store/   状态管理
  utils/   通用工具

4. 遇到问题怎么办

这一块最常被漏，但它省的时间最多。

## 常见问题

**端口被占用**
换端口：npm run dev -- --port 3001

**接口报 401**
检查 .env 里的 TOKEN 是否过期

3. 容易被写坏的三种方式

一、写成宣传页。 “一个强大的、优雅的、现代化的解决方案”——这类句子对使用者没有任何帮助，还占了 README 最前面的位置。

二、命令不写全参数。 只写 npm run dev，不写怎么指定环境变量、怎么换端口。等真要传参数的时候还得回来翻源码。

三、放一张截图当全部说明。 图会过时，文字不会。而且命令行项目根本没界面，截图不解决问题。

4. 写完记得回来改

README 变旧的过程和代码一样：接口改了说明没改、命令加了参数没写、目录调整了说明没动。

比较实际的做法是：每次改完对外的东西，顺手看一眼 README。不是专门排时间做文档维护，是把维护挂在已经要做的事情上。攒两三个月专门花一天整理，通常已经积压到看不动了。

5. 另外两个容易被忽略的 README

一、CHANGELOG。 记下每个版本改了什么。好处有两个：出问题时能快速定位是哪个版本引入的；用户升级时知道该注意什么。

## 1.2.0
- 新增 --format 参数
- 修复 Windows 下路径处理错误

二、CONTRIBUTING。 团队项目才需要，但写了之后能省掉大量"我该怎么做"的提问。内容不多：怎么跑起来、代码规范、提交信息格式、怎么提问题。

6. 最后

判断 README 有没有用的方法很简单：找一个没接触过这个项目的人，让他照着 README 跑起来。 跑不起来的地方就是文档缺的地方，不用再讨论写得好不好。

如果团队里没人愿意当这个测试对象，那可能说明大家都在项目里待久了，而 README 是给新来的那个人写的。