README.md 使用詳解

作者：辰風沐陽閱讀：4728 發布時間：2023-03-12 上次更新：2024-01-19

1. 介紹
2. 規范
3. 徽章
4. 模板
5. 示例

1. 介紹

README.md：項目的自述文件，用于介紹項目整體的一個概覽

README.md 一般出現在 git 倉庫的根目錄下，作用是對項目的主要信息進行描述

如果一個項目很長時間沒有修改了，突然你需要修改這個項目，通過查看 README.md 對項目的描述可以讓你快速上手，當別人接手你的項目或你接手別人的項目也能快速的了解該項目

2. 規范

對于剛接手項目的陌生人，應該通過 README.md 快速獲取到項目內容的要點，因此其內容應該是項目整體的一個概覽。其實這個文件內容有約定俗成的規范，這個規范也是眾多開源開發者相互磨合形成的。文件內容理應圍繞下面內容編寫：

項目介紹
運行環境要求
依賴的第三方插件
部署要素，操作說明
代碼結構說明（目錄結構）
開發環境，測試環境，正式環境域名等參數說明

README.md 內容結構公認比較漂亮的一種是 logo + 徽章 + 正文，Vue 倉庫就是如此：https://github.com/vuejs/vue

很多非開源項目并不會專門設計自述文件的 logo，將 logo 換為項目名稱也是挺好看的，如下所示：

自述文件中對于標題的選用：

項目名稱使用一級標題
項目介紹使用二級標題，項目介紹下面的內容使用三級標題，依次類推

3. 徽章

人活一張臉，樹活一張皮，git 倉庫也不例外，好看的倉庫從 README 開始，而好看的 README 從置頂的小徽章開始

置頂徽章生成網站：https://shields.io/#your-badge

輸入想要的標簽文字和顏色，就可以得到一個最簡單的個性徽章

使用查詢字符串參數 style 可以自定義徽章樣式：

flat 扁平化，默認效果
flat-square 扁平化+去圓角
for-the-badge 扁平化+去圓角+放大
social 社交樣式
plastic 立體效果

https://img.shields.io/badge/Node-12.18.2-yellowgreen?style=plastic

4. 模板

居中的項目 logo：

Markdown 支持內嵌 HTML 代碼，將下面代碼直接放于 README.md 中即可

<p align="center">
    <a href="https://vuejs.org" target="_blank">
        <img width="100" src="https://vuejs.org/images/logo.png">
    </a>
</p>

居中的項目名稱：

<h1 align="center">康盈養老PC管理后臺</h1>

項目名稱下面一般都是放置漂亮的徽章：

<p align="center">
    <img src="https://img.shields.io/badge/PHP-7.3-green" />
    <img src="https://img.shields.io/badge/MySQL-5.7-green" />
    <img src="https://img.shields.io/badge/Node.js-12.18.2-green" />
</p>

自述文件的正文：

## 運行環境
---
| 環境 | 接口域名 | 后臺域名 |
| --- | --- | --- |
| 本地環境 | http://192.168.1.183 | xxx |
| 測試環境 | http://test.itqaq.com | xxx |
| 正式環境 | http://m.837wan.com | xxx |

5. 示例

<p align="center">
    <a href="https://vuejs.org" target="_blank">
        <img width="100" src="https://vuejs.org/images/logo.png">
    </a>
</p>
<h1 align="center">康盈養老PC管理后臺</h1>
<p align="center" style="margin-bottom:16px;">
    <img src="https://img.shields.io/badge/PHP-7.3-green" />
    <img src="https://img.shields.io/badge/MySQL-5.7-red" />
    <img src="https://img.shields.io/badge/Node.js-12.18.2-green" />
</p>
<p align="center">
Vue3 組件庫，Typescirpt 編寫，高性能，支持按需引入、國際化、可配置主題。
</p>
## 項目介紹
---
## 依賴插件
---
| 插件名稱 | 插件官網 |
| --- | --- |
| z-paging | https://z-paging.zxlee.cn |
| uview-ui | https://www.uviewui.com |
## 項目部署
---
## 環境說明
---
| 環境 | 接口域名 | 后臺域名 |
| --- | --- | --- |
| 測試環境 | `https://test.itqaq.com` | https://api.itqaq.com |
| 正式環境 | `https://blog.itqaq.com` | https://api.itqaq.com |