README.md 怎么写?GitHub README 格式与模板

打开一个 GitHub 项目,第一眼看到的就是 README.md。写得好的 README 能让人在 30 秒内知道:这是什么、怎么安装、怎么使用。本文整理 README 的标准结构、常用写法,最后附上可以直接复制的模板。

想边看边写,可以打开 Markdown 在线编辑器,左边写、右边实时看到效果。

README 应该包含什么?

一份好的 README 通常依次包含:

  1. 项目名称与一句话介绍:让人立刻知道它解决什么问题。
  2. 截图或演示:一张图胜过千言万语。
  3. 功能特点:列出 3 到 6 个重点。
  4. 安装方式:复制粘贴就能运行的命令。
  5. 使用方式:最简单的示例。
  6. 配置说明:环境变量、配置文件(如有)。
  7. 参与贡献:如何反馈问题、提交修改。
  8. 许可证:例如 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/screenshot.png)

图片放在项目的 docs/ 或 assets/ 文件夹,用相对路径引用,移动项目也不会失效。

徽章(Badges)

很多 README 开头会有一排小徽章,显示版本、许可证、构建状态:

![License](https://img.shields.io/badge/license-MIT-green)

徽章是加分项,不需要放太多。

用表格整理选项

| 参数 | 默认值 | 说明 |
| --- | --- | --- |
| `port` | `3000` | 服务器端口 |
| `debug` | `false` | 是否显示调试信息 |

更多表格技巧请看 Markdown 表格教程。

用 Mermaid 画架构图

GitHub 支持 Mermaid,可以直接在 README 里画流程图或架构图:

flowchart LR
    A[用户] --> B[前端] --> C[API] --> D[数据库]

详细语法见 Mermaid 图表教程。

README 模板(可直接复制)

# 项目名称

一句话说明这个项目解决什么问题。

![截图](docs/screenshot.png)

## 功能

- 功能一
- 功能二
- 功能三

## 安装

```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。