npm 開發(fā)者指南

介紹

因此，你已經(jīng)決定使用 npm 來開發(fā)（并且可能發(fā)布/部署）你的項(xiàng)目。 這是很好的一件事！ 除了用戶安裝程序所需要執(zhí)行的簡單步驟之外，你可能還需要執(zhí)行另外的一些操作。

關(guān)于文件

這些是手冊頁。 如果你已經(jīng)安裝了 npm，那么我相信你應(yīng)該能夠通過npm thing獲取特定主題的文檔，或者使用npm help thing查看相同的信息。

什么是包（package）？

包是：

1. 包含有 package.json 文件描述的程序的文件夾。
2. 包含有(1)的 gzip 壓縮包。
3. 解析為(2)的網(wǎng)址。
4. <name>@<version>與(3)在注冊表上發(fā)布的(1)。
5. (1)<name>@<tag>指向(4).
6. <name>具有滿足(5)的 “最新” 標(biāo)簽的1.
7. 一個 git Url，克隆時，結(jié)果為(1)。

即使你從沒有發(fā)布過你的包，如果你只是想要寫一個 node 程序(1)，你仍然可以得到使用 npm 的很多好處，或者如果你還希望打包后能夠輕松地安裝到其他地方成一個 tarball(2)。

Git 網(wǎng)址可以采用以下的形式：

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 可以是任何的標(biāo)簽，sha，或者分支，作為參數(shù)被提供給 git checkout。默認(rèn)值是 master。

package.json 文件

你需要 package.json 在項(xiàng)目的根目錄中有一個文件才能使用 npm 執(zhí)行任何操作。這基本上就是整個界面。

有關(guān)于 package.json 這個文件中內(nèi)容，你還需要：

• 名稱：這應(yīng)該是標(biāo)識您的項(xiàng)目的字符串。請不要使用名稱來指定它在節(jié)點(diǎn)上運(yùn)行，還是在 JavaScript 中。您可以使用“引擎”字段來明確說明您的程序需要的節(jié)點(diǎn)（或其他任何版本）的版本，并且可以很好地假設(shè)它是 JavaScript。 它不一定需要與您的 github 存儲庫名稱匹配。 所以，node-foo和bar-js是壞名字。?foo或者bar更好。
• 版本：與 semver 兼容的版本。
• 引擎：指定運(yùn)行程序的節(jié)點(diǎn)（或其他任何版本）的版本。節(jié)點(diǎn) API 變化很大，可能存在您依賴的錯誤或新功能。明確一點(diǎn)。
• 作者：相信一些。
• 腳本：如果你有特殊的編譯或安裝腳本，那么你應(yīng)該把它放在scripts對象中。您絕對應(yīng)該至少有一個基本的冒煙測試命令作為“scripts.test”字段。請參閱npm-scripts。
• main：如果你有一個單一的模塊作為你程序的入口點(diǎn)（就像“foo”包在 require(“foo”) 給你的一樣），那么你需要在“main”字段中指定它。
• 目錄：這是一個將名稱映射到文件夾的對象。最好包括“l(fā)ib”和“doc”，但如果您使用“man”指定一個充滿手冊頁的文件夾，它們將像這些一樣安裝。

你可在包的根目錄中使用 npm init，以便開始使用非?；镜?package.json 文件。

將文件放在包外

使用.npmignore文件將東西放在包外。如果沒有.npmignore文件，但有是一個.gitignore文件，然后將NPM忽略由相匹配的東西.gitignore文件。如果要包含.gitignore文件排除的內(nèi)容，可以創(chuàng)建一個空.npmignore文件來覆蓋它。像git,在包的所有子目錄中npm查找.npmignore和.gitignore文件，而不僅僅是根目錄。

.npmignore文件遵循相同的模式規(guī)則?的.gitignore文件：

• 空行或以 開頭的行將#被忽略。
• 標(biāo)準(zhǔn)的 glob 模式有效。
• 您可以使用正斜杠結(jié)束模式/以指定目錄。
• 您可以通過以感嘆號開頭來否定模式!。

默認(rèn)情況下，以下路徑和文件將被忽略，因此無需.npmignore顯式添加它們：

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

此外，node_modules除了捆綁的依賴項(xiàng)外，所有內(nèi)容都將被忽略。npm 會自動為你處理這個，所以不要費(fèi)心添加node_modules到.npmignore.

以下路徑和文件永遠(yuǎn)不會被忽略，因此將它們添加到?.npmignore毫無意義：

• package.json
• README?（及其變體）
• CHANGELOG?（及其變體）
• LICENSE?/?LICENCE

如果考慮到您的項(xiàng)目結(jié)構(gòu)，您發(fā)現(xiàn).npmignore維護(hù)問題令人頭疼，您可以嘗試填充 的files?屬性package.json，該屬性是應(yīng)包含在您的包中的文件或目錄名稱數(shù)組。有時，白名單比黑名單更容易管理。

測試你的 .npmignore 或 files 配置是否有效

如果您想仔細(xì)檢查您的包是否僅包含您想要發(fā)布的文件，您可以在npm pack本地運(yùn)行該命令，這將在工作目錄中生成一個 tarball，與發(fā)布的方式相同。

鏈接包

npm link旨在安裝開發(fā)包并實(shí)時查看更改，而無需不斷重新安裝。（當(dāng)然，您確實(shí)需要重新鏈接或npm rebuild -g更新已編譯的包。）

發(fā)布前：確保你的軟件包安裝并正常工作

這個很重要。 如果您無法在本地安裝它，則在嘗試發(fā)布它時會遇到問題?；蛘?，更糟糕的是，您將能夠發(fā)布它，但您將發(fā)布一個損壞或毫無意義的包。所以不要那樣做。 在包的根目錄中，執(zhí)行以下操作：

npm install . -g

這會告訴你它正在工作。如果您只想創(chuàng)建一個指向您的工作目錄的符號鏈接包，請執(zhí)行以下操作：

npm link

使用npm ls -g，看看它的存在。 要測試本地安裝，請進(jìn)入其他文件夾，然后執(zhí)行以下操作：

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

將其本地安裝到其他地方的 node_modules 文件夾中。 然后進(jìn)入 node-repl，并嘗試使用 require("my-thing") 引入模塊的主模塊。

創(chuàng)建用戶賬戶

使用 adduser 命令創(chuàng)建用戶。它是這樣工作的：

npm adduser

然后按照提示操作。 這在npm-adduser 中有更好的記錄。

發(fā)布包

這部分很容易。在文件夾的根目錄中，執(zhí)行以下操作：

npm publish

你可以發(fā)布一個 tarball 的 url，或者一個 tarball 的文件名，或者一個文件夾的路徑。

請注意，該文件夾中的幾乎所有內(nèi)容都將?默認(rèn)公開。因此，如果您有秘密內(nèi)容，請使用?.npmignore文件列出要忽略的 glob，或從新結(jié)帳發(fā)布。