npm developer guide

引子

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

原文：npm-developers。

简述

所以，你已经打算使用 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