developers

开发者指南

描述

¥Description

因此，你决定使用 npm 来开发（并且可能发布/部署）你的项目。

¥So, you've decided to use npm to develop (and maybe publish/deploy) your project.

极好的！

¥Fantastic!

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

¥There are a few things that you need to do above the simple steps that your users will do to install your program.

关于这些文件

¥About These Documents

这些是手册页。如果你安装了 npm，你应该能够执行 man npm-thing 来获取有关特定主题的文档，或者执行 npm help thing 来查看相同的信息。

¥These are man pages. If you install npm, you should be able to then do man npm-thing to get the documentation on a particular topic, or npm help thing to see the same information.

什么是包

¥What is a Package

一个包是：

¥A package is:

• a) 包含由 package.json 文件描述的程序的文件夹

  ¥a) a folder containing a program described by a package.json file

• b) 一个 gzipped tarball，包含 (a)

  ¥b) a gzipped tarball containing (a)

• c) 解析为 (b) 的 url

  ¥c) a url that resolves to (b)

• d) 在注册表上发布的 <name>@<version> (c)

  ¥d) a <name>@<version> that is published on the registry with (c)

• e) 指向 (d) 的 <name>@<tag>

  ¥e) a <name>@<tag> that points to (d)

• f) 具有满足 (e) 的 "latest" 标签的 <name>

  ¥f) a <name> that has a "latest" tag satisfying (e)

• g) 一个 git url，在克隆时会导致 (a)。

  ¥g) a git url that, when cloned, results in (a).

即使你从不发布你的包，如果你只是想写一个 node 程序（a），你仍然可以获得使用 npm 的很多好处，也许你还想在打包后能够轻松地安装它成一个 tarball (b)。

¥Even if you never publish your package, you can still get a lot of benefits of using npm if you just want to write a node program (a), and perhaps if you also want to be able to easily install it elsewhere after packing it up into a tarball (b).

Git url 可以是以下形式：

¥Git urls can be of the form:

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 可以是可以作为参数提供给 git checkout 的任何标记、sha 或分支。默认值是存储库用作其默认分支的任何内容。

¥The commit-ish can be any tag, sha, or branch which can be supplied as an argument to git checkout. The default is whatever the repository uses as its default branch.

package.json 文件

¥The package.json File

你需要在项目的根目录中有一个 package.json 文件才能使用 npm 执行大部分操作。这基本上是整个界面。

¥You need to have a package.json file in the root of your project to do much of anything with npm. That is basically the whole interface.

有关该文件中内容的详细信息，请参见 package.json。至少，你需要：

¥See package.json for details about what goes in that file. At the very least, you need:

• name:这应该是一个标识你的项目的字符串。请不要使用名称来指定它在 node 上运行，或者在 JavaScript 中。你可以使用 "engines" 字段来明确说明程序所需的 node 版本（或其他任何版本），并且可以很好地假设它是 JavaScript。

  ¥name: This should be a string that identifies your project. Please do not use the name to specify that it runs on node, or is in JavaScript. You can use the "engines" field to explicitly state the versions of node (or whatever else) that your program requires, and it's pretty well assumed that it's JavaScript.

  它不一定需要与你的 github 存储库名称匹配。

  ¥It does not necessarily need to match your github repository name.

  所以，node-foo 和 bar-js 是坏名字。foo 或 bar 更好。

  ¥So, node-foo and bar-js are bad names. foo or bar are better.

• version:与 semver 兼容的版本。

  ¥version: A semver-compatible version.

• engines:指定程序运行的 node（或其他）版本。Node API 变化很大，可能存在你依赖的错误或新功能。明确。

  ¥engines: Specify the versions of node (or whatever else) that your program runs on. The node API changes a lot, and there may be bugs or new functionality that you depend on. Be explicit.

• author:拿点信用。

  ¥author: Take some credit.

• scripts:如果你有一个特殊的编译或安装脚本，那么你应该把它放在 scripts 对象中。你绝对应该至少有一个基本的烟雾测试命令作为 "scripts.test" 字段。见 脚本。

  ¥scripts: If you have a special compilation or installation script, then you should put it in the scripts object. You should definitely have at least a basic smoke-test command as the "scripts.test" field. See scripts.

• main:如果你有一个模块作为程序的入口点（就像 "foo" 包在 require("foo") 处给你的那样），那么你需要在 "main" 字段中指定它。

  ¥main: If you have a single module that serves as the entry point to your program (like what the "foo" package gives you at require("foo")), then you need to specify that in the "main" field.

• directories:这是一个将名称映射到文件夹的对象。最好包括 "lib" 和 "doc"，但如果你使用 "man" 指定一个充满手册页的文件夹，它们将像这些一样被安装。

  ¥directories: This is an object mapping names to folders. The best ones to include are "lib" and "doc", but if you use "man" to specify a folder full of man pages, they'll get installed just like these ones.

你可以在包的根目录中使用 npm init，以便开始使用非常基本的 package.json 文件。有关详细信息，请参阅 npm init。

¥You can use npm init in the root of your package in order to get you started with a pretty basic package.json file. See npm init for more info.

将文件保留在包之外

¥Keeping files out of your Package

使用 .npmignore 文件将内容保存在你的包之外。如果没有 .npmignore 文件，但有 .gitignore 文件，则 npm 将忽略 .gitignore 文件匹配的内容。如果要包含 .gitignore 文件排除的内容，可以创建一个空的 .npmignore 文件来覆盖它。与 git 一样，npm 在包的所有子目录中查找 .npmignore 和 .gitignore 文件，而不仅仅是根目录。

¥Use a .npmignore file to keep stuff out of your package. If there's no .npmignore file, but there is a .gitignore file, then npm will ignore the stuff matched by the .gitignore file. If you want to include something that is excluded by your .gitignore file, you can create an empty .npmignore file to override it. Like git, npm looks for .npmignore and .gitignore files in all subdirectories of your package, not only the root directory.

.npmignore 文件跟随 相同的模式规则 为 .gitignore 文件：

¥.npmignore files follow the same pattern rules as .gitignore files:

• 空白行或以 # 开头的行将被忽略。

  ¥Blank lines or lines starting with # are ignored.

• 标准 glob 模式有效。

  ¥Standard glob patterns work.

• 你可以使用正斜杠 / 结束模式以指定目录。

  ¥You can end patterns with a forward slash / to specify a directory.

• 你可以通过以感叹号 ! 开头来否定模式。

  ¥You can negate a pattern by starting it with an exclamation point !.

默认情况下，某些路径和文件会被忽略，因此无需明确将它们添加到 .npmignore。以下是一些示例：

¥By default, some paths and files are ignored, so there's no need to add them to .npmignore explicitly. Some examples are:

• .*.swp

• ._*

• .DS_Store

• .git

• .gitignore

• .hg

• .npmignore

• .npmrc

• .lock-wscript

• .svn

• .wafpickle-*

• config.gypi

• CVS

• npm-debug.log

此外，node_modules 中的所有内容都将被忽略，但打包的依赖除外。npm 会自动为你处理此问题，因此不必费心将 node_modules 添加到 .npmignore。

¥Additionally, everything in node_modules is ignored, except for bundled dependencies. npm automatically handles this for you, so don't bother adding node_modules to .npmignore.

以下路径和文件永远不会被忽略，因此将它们添加到 .npmignore 是没有意义的：

¥The following paths and files are never ignored, so adding them to .npmignore is pointless:

• package.json

• README（及其变体）

  ¥README (and its variants)

• CHANGELOG（及其变体）

  ¥CHANGELOG (and its variants)

• LICENSE / LICENCE

如果在给定项目结构的情况下，你发现 .npmignore 是一个令人头疼的维护问题，你可以尝试填充 package.json 的 files 属性，该属性是应该包含在你的包中的文件或目录名称的数组。有时手动选择允许哪些项目比构建阻止列表更容易管理。

¥If, given the structure of your project, you find .npmignore to be a maintenance headache, you might instead try populating the files property of package.json, which is an array of file or directory names that should be included in your package. Sometimes manually picking which items to allow is easier to manage than building a block list.

有关可以和不能忽略的内容的更多信息，请参阅 package.json。

¥See package.json for more info on what can and can't be ignored.

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

¥Testing whether your .npmignore or files config works

如果你想仔细检查你的包在发布时是否只包含你想要的文件，你可以在本地运行 npm pack 命令，这将在工作目录中生成一个 tarball，与发布时相同。

¥If you want to double check that your package will include only the files you intend it to when published, you can run the npm pack command locally which will generate a tarball in the working directory, the same way it does for publishing.

链接包

¥Link Packages

npm link 旨在安装开发包并实时查看更改，而无需不断重新安装。（当然，你确实需要重新链接或 npm rebuild -g 来更新已编译的包。）

¥npm link is designed to install a development package and see the changes in real time without having to keep re-installing it. (You do need to either re-link or npm rebuild -g to update compiled packages, of course.)

更多信息在 npm link。

¥More info at npm link.

发布之前：确保你的软件包安装并正常工作

¥Before Publishing: Make Sure Your Package Installs and Works

这个很重要。

¥This is important.

如果你无法在本地安装它，则尝试发布它会遇到问题。或者，更糟糕的是，你可以发布它，但你将发布一个损坏或毫无意义的包。所以不要那样做。

¥If you can not install it locally, you'll have problems trying to publish it. Or, worse yet, you'll be able to publish it, but you'll be publishing a broken or pointless package. So don't do that.

在包的根目录中，执行以下操作：

¥In the root of your package, do this:

npm install . -g

这会告诉你它正在工作。如果你只想创建一个指向你的工作目录的符号链接包，请执行以下操作：

¥That'll show you that it's working. If you'd rather just create a symlink package that points to your working directory, then do this:

npm link

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

¥Use npm ls -g to see if it's there.

要测试本地安装，请进入其他文件夹，然后执行以下操作：

¥To test a local install, go into some other folder, and then do:

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

将其本地安装到其他地方的 node_modules 文件夹中。

¥to install it locally into the node_modules folder in that other place.

然后进入 node-repl，尝试使用 require("my-thing") 来引入你的模块的主模块。

¥Then go into the node-repl, and try using require("my-thing") to bring in your module's main module.

创建用户账户

¥Create a User Account

使用 adduser 命令创建用户。它是这样工作的：

¥Create a user with the adduser command. It works like this:

npm adduser

然后按照提示进行操作。

¥and then follow the prompts.

这在 npm adduser 中有更好的记录。

¥This is documented better in npm adduser.

发布你的包

¥Publish your Package

这部分很简单。在文件夹的根目录中，执行以下操作：

¥This part's easy. In the root of your folder, do this:

npm publish

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

¥You can give publish a url to a tarball, or a filename of a tarball, or a path to a folder.

请注意，默认情况下该文件夹中的几乎所有内容都会公开。因此，如果你有秘密内容，请使用 .npmignore 文件列出要忽略的 glob，或从新结帐中发布。

¥Note that pretty much everything in that folder will be exposed by default. So, if you have secret stuff in there, use a .npmignore file to list out the globs to ignore, or publish from a fresh checkout.

宣传它

¥Brag about it

在 IRC 中发送电子邮件、写博客、闲聊。

¥Send emails, write blogs, blab in IRC.

告诉世界安装你的程序是多么容易！

¥Tell the world how easy it is to install your program!

也可以看看

¥See also

• npm

• npm init

• package.json

• npm scripts

• npm publish

• npm adduser

• npm registry