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-TW.md,並在開頭互相連結。
寫完之後,把 README.md 拖進墨閱檢查一次排版,確認標題、表格和圖表都正確再推上 GitHub。