README.md 怎么写?GitHub README 格式与模板
打开一个 GitHub 项目,第一眼看到的就是 README.md。写得好的 README 能让人在 30 秒内知道:这是什么、怎么安装、怎么使用。本文整理 README 的标准结构、常用写法,最后附上可以直接复制的模板。
想边看边写,可以打开 Markdown 在线编辑器,左边写、右边实时看到效果。
README 应该包含什么?
一份好的 README 通常依次包含:
- 项目名称与一句话介绍:让人立刻知道它解决什么问题。
- 截图或演示:一张图胜过千言万语。
- 功能特点:列出 3 到 6 个重点。
- 安装方式:复制粘贴就能运行的命令。
- 使用方式:最简单的示例。
- 配置说明:环境变量、配置文件(如有)。
- 参与贡献:如何反馈问题、提交修改。
- 许可证:例如 MIT、Apache-2.0。
小项目可以只写 1、4、5、8,重点是让第一次来的人能顺利跑起来。
常用写法
标题与介绍
# Moread
> 免安装的 Markdown 阅读器,文件不上传。
一份 README 只用一个 # 大标题,其余用 ## 分段。语法细节可以参考 Markdown 语法教程。
安装命令放在代码块里
```bash
git clone https://github.com/you/project.git
cd project
npm install
```
标注语言(bash、python、javascript)能让 GitHub 显示语法高亮。
截图

图片放在项目的 docs/ 或 assets/ 文件夹,用相对路径引用,移动项目也不会失效。
徽章(Badges)
很多 README 开头会有一排小徽章,显示版本、许可证、构建状态:

徽章是加分项,不需要放太多。
用表格整理选项
| 参数 | 默认值 | 说明 |
| --- | --- | --- |
| `port` | `3000` | 服务器端口 |
| `debug` | `false` | 是否显示调试信息 |
更多表格技巧请看 Markdown 表格教程。
用 Mermaid 画架构图
GitHub 支持 Mermaid,可以直接在 README 里画流程图或架构图:
flowchart LR
A[用户] --> B[前端] --> C[API] --> D[数据库]
详细语法见 Mermaid 图表教程。
README 模板(可直接复制)
# 项目名称
一句话说明这个项目解决什么问题。

## 功能
- 功能一
- 功能二
- 功能三
## 安装
```bash
npm install your-package
```
## 使用方式
```javascript
import { hello } from 'your-package';
hello('world');
```
## 配置
| 参数 | 默认值 | 说明 |
| --- | --- | --- |
| `option` | `true` | 说明这个选项 |
## 参与贡献
欢迎提交 Issue 与 Pull Request。
## 许可证
MIT
把模板粘贴到在线编辑器,改成你的内容,再按 Ctrl + S 下载成 README.md。
写好 README 的小技巧
- 先写“怎么跑起来”:大多数人只想知道怎么安装和使用。
- 命令要能直接复制:不要在命令里夹杂说明文字。
- 保持更新:代码改了,README 也要跟着改。
- 长文档加目录:章节很多时,在开头列出各节链接。
- 多语言:可以另外提供
README.zh-CN.md,并在开头互相链接。
写完之后,把 README.md 拖进墨阅检查一遍排版,确认标题、表格和图表都正确再推送到 GitHub。