开源项目README目录规范

README文档的组成部分

看过很多开源框架的README文档，综合一下，项目简介要说明几个你的开源项目用户想迫切了解的问题，这包括：

这个开源项目是做什么的？ 这个项目是什么语言编写的？ 项目维护、CI、依赖更新状态 项目可用版本及其他版本 Demo 或官网地址

所以总结了大概有以下几部分组成：

（一）国际化 （二）项目工程介绍 （三）项目的使用效果图 （四）项目特点 （五）项目的基本结构（架构） （六）集成方式 （七）使用方法 （八）混淆（可选） （九）关于作者/组织及交流方式等信息 （十）贡献者/贡献组织 （十一）鸣谢 （十二）版权信息

国际化

Github是面向全球的一个开源网站，所以不要局限于中文文档，建议写一个英文的README，让来自全球的人都能更方便的了解你的项目。推荐写法，在REAMDE开头写上国际化引用地址：

此外你还可以给项目上面增加一些图标以提高可读性，推荐使用 Shields.io，比如：

项目工程介绍

让别人快速了解项目。项目介绍主要包括：

项目名称、logo（没有logo就不写）：这里推荐一个在线制作 Logo 的网站 Canva

效果图如下所示：

项目的使用效果图

如果是一些自定义控件或者项目的演示效果的，基本都会放上演示效果图，可以是图片，也可以是gif图。 建议：静态的页面的放截图，交互很复杂的建议放gif图。

项目特点

注明这个项目的功能特点，亮点特色会大大提高访客使用这个项目的概率。

比如效果图：

项目的基本结构（架构）（可选）

这里主要介绍项目的各个组成部分，如果是框架，可以附带架构图解；如果是其他的，可以提供一些UML分析图，顺便分析一下源码也行的。

集成方式

这是 README 中最重要的部分，你需要说明这个项目如何使用，这包括：

如何下载这个项目：一般情况下 git clone 该项目地址即可，当然你也可以提供其他包管理下载安装方式； 运行环境：需要的不同环境 项目依赖：你需要说明编译运行这个项目前需要哪些依赖； 安装：你需要说明如何编译安装/运行这个项目； 部署：如果这个项目可以部署的话，请最好注明部署要注意的事项； Debug 方法：理想状况下，你的用户会顺利编译并运行这个项目，但你要确保用户遇到了问题不会来打扰你（如提交 Issues），你还需要提供用户可能会遇到的常见问题；

效果： 工作环境：

如何拉取项目：

安装：

测试debug：

使用方法

关于作者/组织及交流方式等信息：

可以写一下作者或者组织的联系方式，微信，邮箱，博客，微博，甚至支付宝转账二维码等都是可以放上去的。

贡献者/贡献组织

对于一个开源项目来说，令其作者最开心的莫过于有人提交 Pull Request 了。加入一个 CONTRIBUTING 文档将大大提高他人贡献你的项目的概率。

你可以说明你的代码规范，项目架构，如何测试和提交 Pull Request 的正确格式，以及其他有利于开发者进行贡献的信息，这将会使你的项目变得更加的规整如一。你可以在项目根目录新建一个 CONTRIBUTING 进行详细的说明并在 README 中添加其文件锚链接。

比如：

鸣谢

引用了哪些开源技术，这里可以做一些鸣谢，表示对别人的尊重，其实也是一个引用声明，避免因为版权而引起不必要的纠纷。

版权信息

版本很重要，开源许可证很重要，如果没有生命版权，可能会因为一些侵权行为而无法很好的维权，版权信息可以保护作者的权益（个人理解）。

世界上的开源许可证，大概有上百种。很少有人搞得清楚它们的区别。最流行的有六种：GPL、BSD、MIT、Mozilla、Apache、LGPL。 开源许可区别如下图：