npm install安裝離線包的實(shí)現(xiàn)過(guò)程

更新時(shí)間：2025年10月23日 09:39:05 作者：趙民勇

這篇文章主要介紹了npm install安裝離線包的實(shí)現(xiàn)過(guò)程,具有很好的參考價(jià)值,希望對(duì)大家有所幫助,如有錯(cuò)誤或未考慮完全的地方,望不吝賜教

方法一：使用 npm 的離線緩存（最常用、最推薦）

這是最標(biāo)準(zhǔn)的離線安裝方式。它利用了 npm 自身的緩存機(jī)制。

工作原理

在線準(zhǔn)備：在一臺(tái)有網(wǎng)絡(luò)的機(jī)器上，運(yùn)行 npm install 將所有依賴（包括子依賴）完整地下載到 npm 的全局緩存目錄（~/.npm）中。
轉(zhuǎn)移緩存：將整個(gè)緩存目錄打包，復(fù)制到離線機(jī)器上。
離線安裝：在離線機(jī)器上，通過(guò)環(huán)境變量指向這個(gè)準(zhǔn)備好的緩存目錄，并使用 --offline 參數(shù)安裝。

詳細(xì)步驟

在線環(huán)境準(zhǔn)備緩存：

# 1. 在聯(lián)網(wǎng)機(jī)器上，進(jìn)入項(xiàng)目目錄，正常安裝所有依賴
cd my-project
npm install

# 2. 此時(shí)所有包的.tgz文件都已存儲(chǔ)在 ~/.npm 目錄中
# 3. 將整個(gè) ~/.npm 緩存目錄打包拷貝到離線環(huán)境
tar -czf npm-cache.tar.gz ~/.npm

離線環(huán)境安裝：

# 1. 將打包的緩存文件解壓到離線機(jī)器的某個(gè)目錄，例如 /path/to/offline-cache/
tar -xzf npm-cache.tar.gz -C /path/to/offline-cache/

# 2. 設(shè)置環(huán)境變量，讓npm使用這個(gè)準(zhǔn)備好的緩存
export npm_config_cache="/path/to/offline-cache/.npm"

# 3. 強(qiáng)制npm使用離線模式進(jìn)行安裝
npm install --offline

優(yōu)點(diǎn)：能處理復(fù)雜的依賴樹，是管理整個(gè)項(xiàng)目依賴的最佳實(shí)踐。
缺點(diǎn)：需要提前準(zhǔn)備整個(gè)緩存目錄，可能會(huì)很大。

方法二：直接安裝本地.tgz包文件

如果你只有一個(gè)單獨(dú)的離線包文件（.tgz 格式），可以直接安裝它。

操作步驟

# 在聯(lián)網(wǎng)機(jī)器上，打包某個(gè)包
npm pack electron
# 這會(huì)生成一個(gè)類似 electron-28.0.0.tgz 的文件

如何獲取 .tgz 文件？

從 npm registry 官網(wǎng)下載。

使用 npm pack 命令打包一個(gè)你已經(jīng)有的包：

# 在聯(lián)網(wǎng)機(jī)器上，打包某個(gè)包
npm pack electron
# 這會(huì)生成一個(gè)類似 electron-28.0.0.tgz 的文件

優(yōu)點(diǎn)：非常簡(jiǎn)單直接，適合安裝單個(gè)獨(dú)立的包。
缺點(diǎn)：無(wú)法自動(dòng)處理這個(gè)包所依賴的其他包。如果這個(gè) .tgz 包有依賴，而你的離線環(huán)境沒(méi)有，安裝會(huì)失敗。

方法三：從本地文件系統(tǒng)鏈接（file:協(xié)議）

你可以將依賴包放在一個(gè)本地文件夾中（比如一個(gè)U盤或內(nèi)網(wǎng)文件共享），然后在 package.json 中直接指向它。

操作步驟

準(zhǔn)備離線包目錄：在離線環(huán)境中，創(chuàng)建一個(gè)目錄（如 ./offline-packages/）存放所有你需要的包的 .tgz 文件。

修改 package.json：將依賴的版本號(hào)改為 file: 協(xié)議路徑。

{
  "dependencies": {
    "electron": "file:./offline-packages/electron-v28.0.0.tgz",
    "lodash": "file:./offline-packages/lodash-4.17.21.tgz"
  }
}

運(yùn)行安裝：

npm install

優(yōu)點(diǎn)：配置清晰，版本管理方便。
缺點(diǎn)：需要手動(dòng)管理 package.json 中的路徑，同樣可能無(wú)法處理嵌套依賴。

方法四：搭建離線鏡像倉(cāng)庫(kù)（最專業(yè)）

對(duì)于大型團(tuán)隊(duì)或企業(yè)，最徹底的方法是搭建一個(gè)內(nèi)網(wǎng)專用的 npm 鏡像倉(cāng)庫(kù)。

常用工具：Verdaccio、nexus Repository Manager

工作流程：

在可聯(lián)網(wǎng)的機(jī)器上搭建 Verdaccio。
通過(guò) Verdaccio 代理所有 npm 請(qǐng)求，它會(huì)自動(dòng)緩存所有下載過(guò)的包。
將這臺(tái)機(jī)器上的 Verdaccio 存儲(chǔ)目錄打包，遷移到離線網(wǎng)絡(luò)。
在離線網(wǎng)絡(luò)中的機(jī)器上配置 npm registry 指向內(nèi)網(wǎng)的 Verdaccio 地址（如 http://internal-ip:4873/）。
此后，所有 npm install 命令都會(huì)從這個(gè)內(nèi)網(wǎng)鏡像獲取包。

優(yōu)點(diǎn)：對(duì)開發(fā)者最透明，體驗(yàn)與聯(lián)網(wǎng)幾乎無(wú)異，能完美處理所有依賴。

缺點(diǎn)：搭建和維護(hù)有一定復(fù)雜度。

重要注意事項(xiàng)總結(jié)

1.處理嵌套依賴：方法一（緩存）和方法四（鏡像）是唯一能自動(dòng)處理嵌套依賴的方法。方法二和方法三需要你手動(dòng)下載所有子依賴的包，非常繁瑣。

2.Electron 等二進(jìn)制包：對(duì)于像 electron 這樣包含平臺(tái)特定二進(jìn)制文件的包，離線安裝需要額外步驟。除了 npm 緩存，你還需要：

提前下載好對(duì)應(yīng)平臺(tái)的 Electron .zip 文件。
設(shè)置 ELECTRON_MIRROR 或 ELECTRON_OVERRIDE_DIST_PATH 環(huán)境變量來(lái)指向這些文件的存放位置。否則，安裝腳本依然會(huì)嘗試聯(lián)網(wǎng)下載二進(jìn)制文件而導(dǎo)致失敗。

3.版本一致性：離線環(huán)境下，必須嚴(yán)格保證你準(zhǔn)備的離線包版本與 package.json 中要求的版本完全匹配，否則安裝會(huì)失敗。