如何写好开源项目的README-自用Git仓库模板分享

自用 Git 仓库模板分享

文章目录

点我 打开/关闭 目录列表

• 1. README 部分
  • 1.1 简介
  • 1.2 效果展示
• 2. Issue/PR 模板 部分
  • 2.1 简介
  • 2.2 效果展示
• 3. Github Actions CI 部分
  • 3.1 简介
  • 3.2 效果展示

声明：我是 「米司特包」 ，本篇文章 首发 于 「米司博客」 ，其他平台为同步推送，由于网站后续会升级重构，很有可能导致文章路径规则变动，所以就没贴详细链接，进到博客的可以根据标题查找 🔍。

本来决定是要写一篇《如何写好开源项目的 README》的文章的，后来根据自己的一些项目的情况，就把 Issue、PR 和 CI 部分也加了进来，各位看官姥爷可以根据自己的需要查看。

由于作者本人也是一个常逛 Github 的人，偶尔也会在上面找一些别人实现好的轮子，在这中间发现有的一些项目质量很好，但是有的没有提供文档或者 README 写的很简陋，使用者要用的话，就需要自己去阅读源码，才知道怎么使用，我想这可能是很多技术人员的通病——不喜欢写文档，因为我自己是个强迫症，我自己的项目一般都会有 README 或者专门的文档，因为这个原因，我新建了一个 Github 仓库模板库，里面提供了基础的 README 要素 和多语言范本，同时也提供了 Issue 和 PR 模板，以及基于 Github Actions 的 CI 脚本（目前只有 NodeJS 项目和 Hugo 项目的示例）。基本上将大部分开源项目需要的东西包含了进去。

代码仓库：

• https://github.com/misitebao/template-git-repository（Github）
• https://gitee.com/misitebao/template-git-repository（Gitee）

也可以直接点击链接在线上 VSCode 环境预览：VSCode 在线预览

1. README 部分

1.1 简介

README 是一个项目的简介，同时也是 Github 上别人访问你的项目第一眼要看的东西，所以写好 README 不仅能为项目加分，同时也显示出你的专业，让别人可以通过 README 文件，就能对你的项目有一个大致的了解。

本项目 README 文件提供以下内容：

• 项目——Logo 和标语 如果你的项目有一个明显的 logo 标识，那么会增加人们的记忆，特别是工具类软件，标语通常是一句简短的话
• 国际化——因为 Github 为全球社区，所以英文文档是必须的，在此基础上可以加上简体中文，方便英文基础薄弱的人
• 文档目录——以列表的形式展示了目录索引，让人可以一眼找到自己需要内容
• 项目介绍——这里可以详细介绍项目的背景与相关信息
• 图形展示——通常是项目的截图、视频，让他人可以预览项目
• 特色功能——以列表的形式列出项目的亮点，方便他人了解项