【译】【2】npm包发布

本篇为《Node.js At Scale》的第二偏,你将会学习到如何利用你自己的模块拓展npm。本教程将解释版本控制是如何工作的。

npm模块发布

在编写nodejs应用时,在npm上有很多东西可以帮助我们提高生产力。我们不必处理低级的事情,比如从左边填充一个字符串,因为在npm库中已经存在可用的模块了。

这些模块从哪里来

这些模块被存储在一个由CounchDB实例提供支持的巨大的库中。

官方的公共npm库在https://registry.npmjs.org/。它是由CouchDB数据库提供支持。它在https://skimdb.npmjs.com/registry上有一个公共镜像。couchapp的代码可以在https://github.com/npm/npm-registry-couchapp找到。

模块如何使它到库

很多像你一样的人,为他们自己或者同事编写了模块代码,然后他们就将代码分享给关注他们的人。

我何时应该考虑发布

  • 如果你想在项目间分享代码
  • 如果你认为别人可能遇到统一的问题,并且你愿意帮助他们
  • 如果你有一点(甚至更多),你认为你可以在以后使用的代码

创建模块

首先让我们使用npm init -y创建一个模块,这个命令在之前的文章中你已经学习到了。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
"name": "npm-publishing",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"repository": {
"type": "git",
"url": "git+https://github.com/author/modulename"
},
"bugs": {
"url": "https://github.com/caolan/async/issues"
},
"license": "ISC"
}

让我们先暂停一会儿。当你构建一个供他人使用的模块时,package.json中的这些字段是必须的。

首先,你应该给你的模块起一个独特的名称,因为它在npm库中必须是唯一的。确保它不会与任何商标冲突。main字段描述当用户使用require('modulename')引入时,将返回哪个文件。你可以将其保留为默认值,或者设置为项目中的任何文件,但是一定要确保你将其指向了有效的文件名。

keywords也是必须包含的,因为npm将根据这些字段对你的包进行索引,这样人们就可以根据这些关键字在npm上或者其他第三方npm搜索网站上搜索到你的模块。

author字段,很明显,这指的就是你自己。但是如果任何人帮助你开发了你的项目,那么这里包含他们也是极好的。此外,包含你的联系方式也是非常重要的,人们如果愿意,可以通过它联系到你。

repository字段中,你可以看到代码托管的位置,以及bugs部分告诉你,如果在包中发现错误,你可以将bug提交到哪里。要快速跳转到bug报告网站,你可以使用npm bug modulename命令。

许可证

实体许可证以及许可证的采用,将有助于采用Node的大公司。代码是很宝贵的资源,共享它是有成本的。

授权是很难的,但是这个网站](http://choosealicense.com)将帮助你选择一个适合你的需求。

通常,当人们发布他们的模块到npm时,他们用的是 MIT 许可

MIT许可是一个宽松免费的软件许可,起源于麻省理工学院(MIT)。作为一个宽松的许可,它对再使用有着非常有限的限制,因此它有着良好的许可兼容性。

语义化版本

版本控制也是非常重要的,以至于它应当有属于自己的章节去说明。

npm库中的大多数模块都遵循着被称为“语义化版本”的规范。语义化版本将软件的版本描述为由.分隔的3个数字。它描述了当对软件本身进行更改时此版本号如何更改。

给定一个版本号MAJOR.MINOR.PATCH,递增:

  • MAJOR版本:当你进行不兼容的API更改时,使用MAJOR递增
  • MINOR版本:当你以向后兼容的方式添加功能时,使用MINOR递增
  • PATCH版本:当你进行向后兼容的bug修复时,使用PATCH递增

预发布版本的标签以及构建元数据,可用作MAJOR.MINOR.PATCH格式的拓展。

这些数字是提供给机器的,而不是提供给人的。

不要假定,当你经常更改MAJOR版本时,人们会不愿意使用你的库。

你必须使用1.0作为你的起始版本

多数人认为,在软件仍处于测试阶段时,进行更改不应该遵守语义版本控制。他们错了!即使是在测试阶段,向用户传达突破性的更改也非常重要。要始终考虑到想要实验你的项目的用户。

文档

如果你向要将你的代码分享给其他人,那么有一份合适的文档是必须的。在你项目的根目录下,放一个README.md文件通常就足够了。如果你将它发布到npm库,npm将会生成一个类似这样的网站,这些都是自动的。它可以帮助那些尝试使用你代码的人。

在发布之前,请确认你已放置所有文档,并且它们是最新的。

将私密文件放置到你的包外

通过.npmigore文件,将使你的秘密文件或私有文件不被发布。使用它的优势是,你可以将你不想上传的文件添加到.npmigore文件中。
如果你使用.gitignore,npm也将默认使用它。和git一样,npm会在包的所有子目录中查找.npmignore和.gitignore文件,而不是仅仅在根目录中。

鼓励贡献

当你向公众开放你的代码时,你应该考虑给他们添加一些关于如何贡献的指南。确保他们知道如何帮助你处理软件的bug并向模块添加新的功能。

有一些可用的,但是你应该考虑使用github的问题和拉取请求模板

npm发布

现在,你已经了解了发布第一个模块所需要的一切。为此,你可以输入npm publish,这个npm命令行工具将会上传你的代码到npm库中。

恭喜,你的模块已经公开到npm库了。你可以通过公开连接www.npmjs.com/package/yourpackagename访问到你的模块。

如果你向npm公开发布了东西,那么它将会永远保留在那里。想要它不被发现,你基本无计可施。一旦你公开发布到库,任何连接到库的每个其他副本都将复制所有的数据。所以当你发布时一定要小心。

我发布了一些我不想发布的东西

我们都是人,我们都会犯错,但是现在该怎么办呢?近期以来的leftpad丑闻,让npm改变了取消发布策略。如果库中,还没有其他包依赖你的包,那么你可以将它取消发布,但是请记住所有的副本都会拷贝所有的数据,因此某些地方的某些人总是能得到它。如果其他包含任何私密信息,确认你在操作后更改它们,并记住将它们添加到.npmignore文件以进行下一次发布。

私有包

如果你不想或者是由于某些团体原因,不被允许发布代码到公用库,npm允许组织开一个组织帐号,这样,他们可以将代码推送到他们的私有库。你可以通过这种方式,和同事分享你们的私有代码。

想进一步阅读它是如何设置,请阅读https://docs.npmjs.com/misc/scope

企业npm

如果你想更近一步的加强你代码的安全性,你可以自己运行一个npm库,这是很容易的。npm有一个可以运行在公司防火墙内的内部版本。你可以阅读关于设置企业npm的更多信息

建构

现在,你已经知道了所有的这些,去构建一些东西吧。如果你是一个有点夸耀的人,那么确保你在twitter上给我们发消息,告诉我们这个教程帮助你构建的包的名称。如果你有任何问题,你会在评论中发现我的。

祝你发布愉快!

在《Node.js At Scale》系列的下一章节,你将会学到关于nodejs的模块系统和如何引用模块。