一份能带来使用者的 GitHub README 应该写什么

开发者从搜索结果、社区链接或依赖关系进入仓库时，通常没有你的背景知识。README 应当帮助他们判断项目是否适合自己，并尽快完成一次真实体验。

第一屏回答四个问题

说明项目是什么、适合谁、解决什么问题，以及如何开始。放一张清晰截图或短演示，并提供文档、在线体验和安装入口。徽章可以保留与判断相关的内容，例如构建状态和当前版本，避免让装饰挤占介绍空间。

下面的 Markdown 是结构示例，需要替换为你项目的真实信息：

# Project name

A [tool type] for [audience] to [specific outcome].

[Live demo](https://example.com) · [Documentation](./docs/)

## Quick start
## Example
## Configuration
## Troubleshooting
## Contributing
## License

快速开始只走一条最短路径

明确运行环境、安装方式、启动命令和预期结果。先支持一条经过验证的路径，再把 Docker、源码构建等替代方法放到后面。

示例不要依赖你机器里的隐藏配置。需要 API Key 时，提供不含真实密钥的配置模板，解释权限、费用和安全存储方式。不要要求用户把密钥提交到公开仓库。

示例应该能验证结果

为核心能力提供一组可复制的输入与预期输出。如果输出具有随机性，描述合理范围或检查方式。复杂项目可以提供独立示例目录，并在发布版本时检查示例是否仍能运行。

说明哪些环境已经测试，哪些暂未支持。遇到常见错误时，提供症状、原因和处理步骤，而不仅是“重新安装试试”。

说明维护与贡献方式

提供问题模板，要求最小复现、版本与必要日志，同时提醒不要上传密码和私人数据。标记适合首次贡献的任务，说明格式检查和提交流程。

选择并展示许可证。若项目处于实验状态、接口可能改变或维护时间有限，直接说明，这能帮助使用者作出合理决定。

用一次实际体验检查文档

请一位未参与开发的人从空目录开始，照着 README 完成核心任务。只观察，不抢先解释。每一次他停下来提问的地方，都是文档可以改进的线索。

完善后，把 README 与GitHub 推广路径结合起来，衡量演示访问和实际使用，而不仅是 Star 数。

官方参考：GitHub README 文档。