極狐GitLab 是 GitLab 在中國的發行版,關于中文參考文檔和資料有:
- 極狐GitLab 中文文檔
- 極狐GitLab 中文論壇
- 極狐GitLab 官網
軟件包庫中的 npm 包 (BASIC ALL)
npm 是 JavaScript 和 Node.js 的默認包管理器。開發者使用 npm 共享和重用代碼,管理依賴項和簡化項目工作流。在極狐GitLab 中,npm 包在軟件開發生命周期中的重要角色。
對于 npm 包管理器客戶端使用的特定 API 端點的文檔,請參見 npm API 文檔。
了解如何構建 npm 或 yarn 包。
對軟件包倉庫進行認證
您必須對軟件包倉庫進行認證來發布或安裝來自私有項目或私有群組的軟件包。如果項目獲群組是公開的,則您無需認證。如果項目是內部的,則您必須是極狐GitLab 實例的注冊用戶。匿名用戶無法從內部項目中拉取軟件包。
要進行認證,您可以使用:
- 一個具有
api
范圍的個人訪問令牌。 - 一個具有
read_package_registry
或/和write_package_registry
范圍的部署令牌。 - 一個 CI 作業令牌。
如果您的阻止在使用雙因素認證(2FA),您必須使用具有 api
范圍的個人訪問令牌。如果您通過 CI/CD 流水線發布軟件包,則您必須使用 CI 作業令牌。更多詳情,可查閱令牌指南。
不要使用文檔中未寫明的認證方法。未寫明的認證方法可能在將來刪除。
使用 .npmrc
進行認證
在您 package.json
文件的同一目錄中創建或編輯 .npmrc
文件。在 .npmrc
文件中包含以下行:
//your_domain_name/api/v4/projects/your_project_id/packages/npm/:_authToken="${NPM_TOKEN}"
如果您正安裝:
- 從實例:
//your_domain_name/api/v4/packages/npm/:_authToken="${NPM_TOKEN}"
- 從群組:
//your_domain_name/api/v4/groups/your_group_id/-/packages/npm/:_authToken="${NPM_TOKEN}"
- 從項目:
//your_domain_name/api/v4/projects/your_project_id/packages/npm/:_authToken="${NPM_TOKEN}"
在這些示例中:
- 將
your_domain_name
替換為您的域名,例如gitlab.com
。 - 將
your_group_id
替換為您在群組主頁中找到的群組 ID。 - 將
your_project_id
替換為您在 項目概覽頁 中找到的項目 ID。 - 將
your_token
替換為部署令牌,群組訪問令牌、項目訪問令牌或個人訪問令牌。
WARNING:千萬不要在 .npmrc
文件中直接硬編碼極狐GitLab 令牌(或任何令牌),也不要在可以提交到倉庫的任何其他文件中硬編碼令牌。
使用 npm config set
進行認證
要這么做:
npm config set -- //your_domain_name/:_authToken=your_token
對于版本 7 及更早版本,使用完整的端點 URL。
如果您正在安裝:
- 從實例:
npm config set -- //your_domain_name/api/v4/packages/npm/:_authToken=your_token
- 從群組:
npm config set -- //your_domain_name/api/v4/groups/your_group_id/-/packages/npm/:_authToken=your_token
- 從項目:
npm config set -- //your_domain_name/api/v4/projects/your_project_id/packages/npm/:_authToken=your_token
在這些示例中:
- 將
your_domain_name
替換為您的域名,例如gitlab.com
。 - 將
your_group_id
替換為您在群組主頁中找到的群組 ID。 - 將
your_project_id
替換為您在 項目概覽頁 中找到的項目 ID。 - 將
your_token
替換為部署令牌,群組訪問令牌、項目訪問令牌或個人訪問令牌。
NOTE:在 npm 版本 8 及以后版本中,您可以在 _authToken
參數中使用 URI 片段代替完整 URL。然而,群組特定端點不受支持。
設置倉庫 URL
要從極狐GitLab 軟件包倉庫發布或安裝軟件包,您需要配置 npm 以正確使用倉庫 URL。配置方法和 URL 結構取決于您是否發布或安裝軟件包。
在配置倉庫 URL 之前,了解不同配置方法的范圍是非常重要的:
-
.npmrc
文件:配置是文件所在文件夾的本地配置。 -
npm config set
命令:這將修改全局 npm 配置,并影響在您系統上運行的所有 npm 命令。 -
publishConfig
在package.json
中:此配置僅適用于發布該軟件包,只適用于發布該軟件包。
WARNING:運行 npm config set
更改全局 npm 配置。此更改影響您的系統上運行的所有 npm 命令,無論當前工作目錄是什么。使用此方法時要小心,尤其是在共享系統上。
發布軟件包
當發布軟件包時,使用項目端點。URL 結構是:
https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/
將 gitlab.example.com
替換為您的極狐GitLab 實例域名,將 <project_id>
替換為您的項目 ID。要配置此 URL,使用如下的方法:
::Tabs
:::TabTitle .npmrc file
在您的項目根目錄下創建或編輯 .npmrc
文件:
@scope:registry=https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/ //gitlab.example.com/api/v4/projects/<project_id>/packages/npm/:_authToken="${NPM_TOKEN}"
:::TabTitle npm config
使用 npm config set
命令
npm config set @scope:registry=https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/
:::TabTitle package.json
將 publishConfig 部分添加到您的 package.json
中:
{"publishConfig": {"@scope:registry": "https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/"}
}
::EndTabs
用您的軟件包范圍替換 @scope
。
安裝軟件包
當安裝軟件包時,您可以使用項目、群組或實例級端點。端點結構會根據不同情況變化:
您可以使用如下之一的方法來配置這些 URL:
當您安裝軟件包時,您可以使用項目、群組或實例端點。端點結構會根據不同情況變化。要配置這些 URL,使用以下之一的方法:
::Tabs
:::TabTitle .npmrc file
在您項目的根目錄下,創建或編輯 .npmrc
文件。根據需要使用適當的 URL:
- 針對項目:
npm config set @scope:registry=https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/
- 針對群組:
npm config set @scope:registry=https://gitlab.example.com/api/v4/groups/<group_id>/-/packages/npm/
- 針對實例:
npm config set @scope:registry=https://gitlab.example.com/api/v4/packages/npm/
:::TabTitle npm config
和適當的 URL 一起使用 npm config set
命令:
- 針對項目:
npm config set @scope:registry=https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/
- 針對群組:
npm config set @scope:registry=https://gitlab.example.com/api/v4/groups/<group_id>/-/packages/npm/
- 針對實例:
npm config set @scope:registry=https://gitlab.example.com/api/v4/packages/npm/
::EndTabs
將 gitlab.example.com
、<project_id>
、<group_id>
和 @scope
替換為您的極狐GitLab 實例和軟件包的值。
當您配置玩您的倉庫 URL 后,參閱認證部分內容進行認證設置。
發布到極狐GitLab 軟件包倉庫
要將 npm 軟件包發布到極狐GitLab 軟件包倉庫,您必須是被認證的。
命名約定
取決于您安裝的軟件包,您可能需要遵循命名約定。
您可以使用三個 API 端點之一來安裝軟件包:
-
實例:當您有多個 npm 軟件包在不同的極狐GitLab 群組或在自己的命名空間中時使用。
-
群組:當您有多個 npm 軟件包在不同的項目下,且它們位于相同的群組或子群組時使用。
-
項目:當您有少量的 npm 軟件包,它們不在相同的極狐GitLab 群組時使用。
如果您有計劃從 項目 或 群組 安裝軟件包,那么您不必遵循命名約定。
如果您計劃從實例 安裝軟件包,那么您必須使用范圍命名您的軟件包。范圍軟件包以 @
開頭,格式為 @owner/package-name
。您可以在 .npmrc
文件中設置范圍,或通過在 package.json
中使用 publishConfig
選項來設置范圍。
- 用于
@scope
的值是托管軟件包的項目的根名稱,而不是擁有該軟件包自身源代碼的項目的根名稱。作用域名稱應該使用小寫形式。 - 軟件包名稱可以是任何您想要的名稱
項目 URL | 所在的軟件包 | 范圍 | 完整的軟件包名稱 |
---|---|---|---|
https://gitlab.com/my-org/engineering-group/analytics | Analytics | @my-org | @my-org/package-name |
確保您在 package.json
文件中的軟件包名稱符合此約定:
"name": "@my-org/package-name"
通過命令行發布軟件包
當您完成認證后,發布軟件包:
npm publish
如果您使用 .npmrc
文件進行認證,設置預期環境變量:
NPM_TOKEN=your_token npm publish
您的軟件包現在應該發布到了軟件包倉庫。
如果上傳的軟件包有多個 package.json
文件,只使用第一個找到的,并忽略其他的。
通過使用 CI/CD 流水線發布軟件包
當使用 CI/CD 流水線發布軟件包時,您可以使用預定義變量 ${CI_PROJECT_ID}
和 ${CI_JOB_TOKEN}
來使用您項目的軟件包倉庫進行認證。我們使用這些變量在 CI/CD 流水線執行時創建 .npmrc
文件來進行認證。
WARNING:當生成 .npmrc
文件時,不要在 ${CI_SERVER_HOST}
后指定默認端口,例如 80
或 443
。
在包含您 package.json
文件的極狐GitLab 項目中,編輯或創建一個 .gitlab-ci.yml
文件。例如:
default:image: node:lateststages:- deploypublish-npm:stage: deployscript:- echo "@scope:registry=https://${CI_SERVER_HOST}/api/v4/projects/${CI_PROJECT_ID}/packages/npm/" > .npmrc- echo "//${CI_SERVER_HOST}/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}" >> .npmrc- npm publish
- 將
@scope
替換為要發布的軟件包的范圍。
當流水線中的 publish-npm
作業運行時,您的軟件包將發布到軟件包倉庫。
安裝軟件包
如果多個軟件包具有相同的名稱和版本,當您安裝軟件包時,最近發布的軟件包將被檢索。
您可以從極狐GitLab 項目、群組或實例安裝軟件包:
-
實例:在您有許多 npm 包在不同的極狐GitLab 群組或在自己的命名空間中時使用。
-
群組:在您有許多項目在同一極狐GitLab 群組中時使用。
-
項目:在您有少量軟件包,它們不在同一個極狐GitLab 群組中時使用。
從實例安裝
WARNING:要從實例安裝軟件包,軟件包必須遵循命名約定來發布。
1.對軟件包倉庫進行認證。
2.設置倉庫:
npm config set @scope:registry https://your_domain_name.com/api/v4/packages/npm/
- 將
@scope
替換為您要從其安裝軟件包的項目的根級別群組。 - 將
your_domain_name
替換為您的域名,例如gitlab.com
。 - 將
your_token
替換為部署令牌,群組訪問令牌、項目訪問令牌或個人訪問令牌。
3.安裝軟件包:
npm install @scope/my-package
從群組安裝
- 引入于極狐GitLab 16.0,使用名為
npm_group_level_endpoints
的功能標志。默認禁用。- 在極狐GitLab 16.1 中 GA,功能標志
npm_group_level_endpoints
被移除。
1.對軟件包倉庫進行認證。
2.設置倉庫:
npm config set @scope:registry=https://your_domain_name/api/v4/groups/your_group_id/-/packages/npm/
- 將
@scope
替換為您要從其安裝軟件包的項目的根級別群組。 - 將
your_domain_name
替換為您的域名,例如 gitlab.com。 - 將
your_group_id
替換為您的群組 ID,可以在群組的主頁中找到。
3.安裝軟件包:
npm install @scope/my-package
從項目安裝
1.對軟件包倉庫進行認證。
2.設置倉庫:
npm config set @scope:registry=https://your_domain_name/api/v4/projects/your_project_id/packages/npm/
- 將
@scope
替換為您要從其安裝軟件包的項目的根級別群組。 - 將
your_domain_name
替換為您的域名,例如gitlab.com
。 - 將
your_project_id
替換為您在 項目概覽頁 中找到的項目 ID。
3.安裝軟件包
npm install @scope/my-package
軟件包轉發至 npmjs.com
- 引入于極狐GitLab 12.9。
- 在 GitLab 17.0 中,角色從維護者更改為所有者。
當在軟件包倉庫中未找到 npm 軟件包時,極狐GitLab 將響應 HTTP 重定向,以便請求客戶端可以重新發送請求到 npmjs.com。
管理員可以在持續集成設置中禁用此行為。
群組所有者可以在群組的 軟件包和倉庫 設置中禁用此行為。
棄用一個軟件包
- 引入于極狐GitLab 16.0。
您可以棄用一個軟件包以便在獲取該軟件包時顯示棄用警告。
先決條件:
-
和刪除軟件包相同的權限。
-
對軟件包倉庫進行認證。
從命令行中,運行:
npm deprecate @scope/package "Deprecation message"
CLI 還可以接受 @scope/package
的版本范圍。比如:
npm deprecate @scope/package "All package versions are deprecated"
npm deprecate @scope/package@1.0.1 "Only version 1.0.1 is deprecated"
npm deprecate @scope/package@"< 1.0.5" "All package versions less than 1.0.5 are deprecated"
移除棄用警告
要移除軟件包棄用警告,請為消息指定空字符串(空字符串)。比如:
npm deprecate @scope/package ""
使用小貼士
從其他組織安裝 npm 軟件包
您可以將軟件包請求路由至極狐GitLab 之外的組織和用戶。
要這么做,請在 .npmrc
文件中添加行。替換 @my-other-org
為您的組織或群組,并使用您組織的 URL。名稱是大小寫敏感的,必須與您的組織或群組名稱完全匹配。
@scope:registry=https://my_domain_name.com/api/v4/packages/npm/
@my-other-org:registry=https://my_domain_name.example.com/api/v4/packages/npm/
npm 元數據
極狐GitLab 軟件包倉庫將如下屬性暴露給 npm 客戶端:
-
name
-
versions
-
name
-
version
-
deprecated
-
dependencies
-
devDependencies
-
bundleDependencies
-
peerDependencies
-
bin
-
directories
-
dist
-
engines
-
_hasShrinkwrap
-
hasInstallScript
:如果此版本具有安裝腳本,則為true
。
-
添加 npm 發行版標簽
您可以為新發布的軟件包添加發行版標簽。標簽是可選的,只能為一個軟件包分配一個標簽。
當您發布一個沒有標簽的軟件包時,默認使用 latest
標簽。當您安裝一個未指定標簽或版本的軟件包時,則使用 latest
標簽。
支持的 dist-tag
命令示例:
npm publish @scope/package --tag # Publish a package with new tag
npm dist-tag add @scope/package@version my-tag # Add a tag to an existing package
npm dist-tag ls @scope/package # List all tags under the package
npm dist-tag rm @scope/package@version my-tag # Delete a tag from the package
npm install @scope/package@my-tag # Install a specific tag
從 CI/CD
- 引入于極狐GitLab 15.10。
您可以使用CI_JOB_TOKEN
或部署令牌在極狐GitLab CI/CD 作業中運行 npm dist-tag
命令。比如:
npm-deploy-job:script:- echo "//${CI_SERVER_HOST}/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}">.npmrc- npm dist-tag add @scope/package@version my-tag
由于 npm 6.9.0 的一個 bug,刪除分發標簽失敗。確保您的 npm 版本是 6.9.1 或更高版本。
支持的 CLI 命令
極狐GitLab npm 倉庫支持如下的 npm CLI (npm
) 和 yarn CLI (yarn
) 命令:
-
npm install
:安裝 npm 軟件包。 -
npm publish
:發布 npm 軟件包到倉庫。 -
npm dist-tag add
:為 npm 軟件包添加發行版標簽。 -
npm dist-tag ls
:列出軟件包的發行版標簽。 -
npm dist-tag rm
:刪除發行版標簽。 -
npm ci
:直接從您的package-lock.json
文件中安裝 npm 軟件包。 -
npm view
:展示軟件包元數據。 -
npm pack
:從軟件包創建 tarball。 -
npm deprecate
:棄用軟件包版本。
故障排查
npm 日志顯示不正確
您可能會遇到如下錯誤:
npm ERR! A complete log of this run can be found in: .npm/_logs/<date>-debug-0
如果日志沒有出現在.npm/_logs/
目錄中,您可以復制日志到根目錄,然后在那里查看它:
script:- npm install --loglevel verbose- cp -r /root/.npm/_logs/ .artifacts:paths:- './_logs
npm 日志會想產物一樣被拷貝至 /root/.npm/_logs/
。
在執行 npm install
或 yarn
時候出現 404 Not Found
錯誤
使用 CI_JOB_TOKEN
來安裝依賴于另外一個項目中的 npm 軟件包時,您可能會遇到 404 Not Found 錯誤。您需要使用具有訪問包和所有依賴項的令牌進行認證。
如果軟件包和其依賴項位于不同的項目,但位于同一群組,您可以使用群組部署令牌:
//gitlab.example.com/api/v4/packages/npm/:_authToken=<group-token>
@group-scope:registry=https://gitlab.example.com/api/v4/packages/npm/
如果軟件包和它的依賴在多個群組中,您可以使用具有訪問所有群組或單個項目用戶的個人訪問令牌:
//gitlab.example.com/api/v4/packages/npm/:_authToken=<personal-access-token>
@group-1:registry=https://gitlab.example.com/api/v4/packages/npm/
@group-2:registry=https://gitlab.example.com/api/v4/packages/npm/
WARNING:要小心對待個人訪問令牌。閱讀我們的令牌安全考量來管理個人訪問令牌(例如,設置短期到期日期和使用最小范圍)。
npm publish
指向默認的 npm 倉庫 (registry.npmjs.org)
請確保您軟件包的范圍在您的 package.json
文件和 .npmrc
文件中一致。
比如,如果您在極狐GitLab 中的項目名稱為 @scope/my-package
,那么您的 package.json
文件應該如下所示:
{"name": "@scope/my-package"
}
以及 .npmrc
文件應該如下所示:
@scope:registry=https://your_domain_name/api/v4/projects/your_project_id/packages/npm/
//your_domain_name/api/v4/projects/your_project_id/packages/npm/:_authToken="${NPM_TOKEN}"
npm install
返回 npm ERR! 403 Forbidden
如果您遇到此錯誤,請確保:
-
在您的項目設置中啟用了軟件包倉庫。盡管默認情況下該功能是啟用的,但您可以禁用它。
-
您的令牌沒有過期且具有適當的權限。
-
在給定范圍內不存在同名或同版本的軟件包。
-
給定范圍的軟件包倉庫 URL包含尾隨斜杠:
-
正確:
//gitlab.example.com/api/v4/packages/npm/
-
錯誤:
//gitlab.example.com/api/v4/packages/npm
-
npm publish
返回 npm ERR! 400 Bad Request
如果您遇到此錯誤,可能是以下問題導致的。
軟件包名稱不符合名稱約定
您的軟件包名稱可能不符合 @scope/package-name 軟件包命名約定。
確保名稱符合約定,包括大小寫。然后再次嘗試發布。
軟件包已存在
您的軟件包已經發不到了相同 root 命名空間下的其他項目中,因此無法使用相同的名稱再次發布。
即使之前發布的軟件包名稱相同,但版本不同,也是如此。
軟件包 JSON 文件過大
請確保您的 package.json
文件不超過 20,000 字符。