【译】npm developer guide

引子

在 npm Getting started 之后，发现了 npm-developers 这篇文档，介绍从开始、本地测试、打包到发布的一个相对完整的流程。感觉是 Getting started 的一个补充，于是就把篇文档翻译成中文，加深下印象。

原文：npm-developers。

• Origin
• My GitHub

简述

所以，你已经打算使用 npm 来开发（并且可能发布或部署）你的项目了。

太棒了！

在你的用户安装程序的简单步骤之上，您需要做一些事情。

关于这些文档

这些是手册页。如果你安装了 npm，你应该可以在 npm 手册中找到特定主题的文档，或者通过 npm 帮助来获取相同的信息。

一个 package 是什么

一个 package 是：

1. 一个包含了描述程序的 package.json 文件的文件夹。
2. 包含有一个 gzip 压缩的压缩包（在 1 的基础上）。
3. 一个解析为（2）中包的 url。
4. 一个已经在登记处发布的 <name>@<version>（在 3 的基础上）。
5. 一个指向的（4）的 <name>@<tag>。
6. 一个满意的有 “latest” 标签的 <name>（在 5 的基础上）。
7. 一个克隆的 git 仓库链接，指向（1）中的文件夹。

即使你从来没有发布过你的包，如果你只是想写一个 node 项目，或者在打包成压缩包后，你想在其它地方能很容易的安装，你仍然可以从使用 npm 中受益匪浅。

Git 的链接可是下面的一些形式：

git://github.com/user/project.git#commit-ish
git+ssh://user@hostname:project.git#commit-ish
git+http://user@hostname/project/blah.git#commit-ish
git+https://user@hostname/project/blah.git#commit-ish

commit-ish 可以是任何的 tag、sha 或者能够提供给 git checkout 作为参数的分支名。默认值是 master。

package.json 文件

你需要在项目根目录下有个 package.json 文件，这样才能用 npm 做很多事情。这基本上就是整个交接口。

详细的文件信息，可见 package.json。你至少需要知道的有：

• name：这个应该是标识你项目的字符串。请不要使用 name 来指明这个项目是基于 node 或者使用了 JavaScript。你可以用 “engines” 字段来表明你项目，需要什么版本的 node（或者其它什么），它几乎假设是 JavaScript。
  也不需要匹配你的 github 库的名称。
  因此，node-foo 和 bar-js 是不好的命名。foo 和 bar 的命名会更好。
• version：semver 兼容版本。
• engines：指明你的项目基于那个版本 node（或其它什么） 运行。node API 改变很频繁，你依赖的版本，可能有一些 bug 或新的功能。明确的指出来。
• author：作者。
• scripts：如果你有特定的编译或安装脚本，那么你应该把它放到 scripts 对象中。你应该至少有一个基本的 smoke test 命令作为 “scripts.test” 字段。见 npm-scripts。
• main：如果你有一个单独的模块作为你程序的入口（就像 “foo” 包通过 requre("foo") 获取），那么你需要在 “main” 字段指明。
• directories：这是一个映射名称到文件夹的对象。最好包括 “lib” 和 “doc”，但是如果你使用 “man” 指定一个满是手册页的文件夹，它们将会像安装这些手册页一样进行安装。

你可以在你项目的根目录下，使用 npm init 初始化基本的 package.json 文件。更多信息见 npm-init。

过滤文件

使用 .npmignore 文件排除包中的一些东西。如果没有 .npmignore 文件，但有 .gitignore 文件，那么 npm 将忽略该文件中匹配到的东西。如果你想包含你 .gitignore 文件中排除的文件，你可以创建一个空的 .npmignore 文件覆盖它。与 git 一样，npm 在包的所有子目录中查找 .npmignore 和 .gitignore 文件，而不仅仅是根目录。

.npmignore 跟 .gitignore 遵循相同的规则模式：

• 以 # 开始的行会被忽略。
• 标准的全局模式有效。
• 你可以使用正斜杠结束模式 / 指定目录。
• 你可以通过使用感叹号 ！来否定一个模式。

默认的，下面的路径和文件会被忽略，因此不需要额外将这些添加到 .npmignore 中：

• .*.swp
• ._*
• .DS_Store
• .git
• .hg
• .npmrc
• .lock-wscript
• .svn
• .wafpickle-*
• config.gypi
• CVS
• npm-debug.log

此外，node_module 中所有的东西会被忽略，除了绑定的依赖。npm 会自动为你处理这个。所以不必将 node_module 加入到 .npmignore 中。

下面的路径和文件绝不会被忽略，所以把这些加入到 .npmignore 中没有意义：

• package.json
• README (and its variants)
• CHANGELOG (and its variants)
• LICENSE / LICENCE

如果考虑到项目的结构，你发现 .npmignore 是一个维护难题，那么可以尝试填充 package.json 文件的 files 属性，该属性是一个数组，里面是应该包含在包中的文件或目录名。有时候白名单比黑名单更容易管理。

测试你的 .npmignore 或文件配置是否有效

如果你想要再次确认，当发布时，你想要的都包含在包中，你可以本地运行 npm pack 命令，这个命令将在工作目录生成一个压缩包，发布包也是使用这种方式。

Link 包

npm link 旨在安装一个开发包并实时查看更改，而不用再次重新安装。（当然，你需要重新 link 或 npm rebuidl -g 来更新编译的包。）

实际操作见本地包调试 ：npm link ，文档信息见 npm-link。

发布之前：确保你的包可正常安装运行

这很重要。

如果你的包不能本地安装，你试图发布它，将会有问题。或者更糟糕的是，你能发布，但发布了一个破损或者无意义的包。所以不要这样做。

在你包的根目录下，执行下面命令：

npm install . -g

这将会告诉你是否可行。如果你更喜欢创建一个 link 的包，指向你的工作目录，那么这么做：

npm link

使用 npm ls -g 查看是否存在。

测试本地安装，到另外一个文件夹下，执行：

cd ../some-other-folder
npm install ../my-package

在其它地方，本地安装到 node_module 文件夹下。

然后进入 node-repl，尝试使用 require（“my-thing”）引入你模块的主模块。

创建一个用户账户

通过 adducer 命令创建一个用户。像这样运行：

npm adduser

之后就根据提示进行。详细见 npm-adduser。

发布你的包

这部分很简单。到你文件夹根目录下，执行这个：

npm publish

你可以给一个压缩包，一个压缩包的文件名，或者一个文件夹的路径发布一个 url。

请注意，默认情况下，文件夹里面几乎所有的内容将会被公开。所以，如果你在里面有秘密的东西，使用一个 .npmignore 文件列出要全局忽略的东西，或者从一个新的 checkout 发布。

参考资料

• npm-developers