GitLab NPM Registry · Gitlab 中文文檔

# GitLab NPM Registry > 原文：[https://docs.gitlab.com/ee/user/packages/npm_registry/](https://docs.gitlab.com/ee/user/packages/npm_registry/) * [Enabling the NPM Registry](#enabling-the-npm-registry) * [Getting started](#getting-started) * [Installing NPM](#installing-npm) * [Installing Yarn](#installing-yarn) * [Creating a project](#creating-a-project) * [Authenticating to the GitLab NPM Registry](#authenticating-to-the-gitlab-npm-registry) * [Authenticating with a personal access token or deploy token](#authenticating-with-a-personal-access-token-or-deploy-token) * [Using variables to avoid hard-coding auth token values](#using-variables-to-avoid-hard-coding-auth-token-values) * [Authenticating with a CI job token](#authenticating-with-a-ci-job-token) * [Uploading packages](#uploading-packages) * [Uploading a package with the same version twice](#uploading-a-package-with-the-same-version-twice) * [Package naming convention](#package-naming-convention) * [Installing a package](#installing-a-package) * [Forwarding requests to npmjs.org](#forwarding-requests-to-npmjsorg) * [Removing a package](#removing-a-package) * [Publishing a package with CI/CD](#publishing-a-package-with-cicd) * [Troubleshooting](#troubleshooting) * [Error running yarn with NPM registry](#error-running-yarn-with-npm-registry) * [`npm publish` targets default NPM registry (`registry.npmjs.org`)](#npm-publish-targets-default-npm-registry-registrynpmjsorg) * [`npm install` returns `Error: Failed to replace env in config: ${NPM_TOKEN}`](#npm-install-returns-error-failed-to-replace-env-in-config-npm_token) * [`npm install` returns `npm ERR! 403 Forbidden`](#npm-install-returns-npm-err-403-forbidden) * [NPM dependencies metadata](#npm-dependencies-metadata) * [NPM distribution tags](#npm-distribution-tags) # GitLab NPM Registry[](#gitlab-npm-registry-premium "Permalink") [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7. 使用 GitLab NPM 注冊表，每個項目都可以擁有自己的空間來存儲 NPM 軟件包. [![GitLab NPM Registry](https://img.kancloud.cn/d3/a1/d3a15b23b0e659f05e69d8becf54ccdd_2526x832.png)](img/npm_package_view_v12_5.png) **注意：**僅支持[作用域的](https://s0docs0npmjs0com.icopy.site/misc/scope)程序包. ## Enabling the NPM Registry[](#enabling-the-npm-registry "Permalink") **注意：**僅當您的 GitLab 管理員[啟用了對 NPM 注冊表的支持時，](../../../administration/packages/index.html)此選項才可用. 啟用 NPM 注冊表后，默認情況下它將可用于所有新項目. 要為現有項目啟用它，或者要禁用它： 1. 導航到項目的**"設置">"常規">"可見性，項目功能，權限"** . 2. 找到"軟件包"功能并啟用或禁用它. 3. 單擊**保存更改**以使更改生效. 然后，您應該能夠在左側欄中看到" **程序包和注冊表"**部分. 在繼續使用 GitLab NPM 注冊表進行身份驗證之前，您應該熟悉軟件包的命名約定. ## Getting started[](#getting-started "Permalink") 本節將介紹安裝 NPM（或 Yarn）并為您的 JavaScript 項目構建軟件包. 如果您不熟悉 NPM 軟件包，這是一個快速入門. 如果您已經在使用 NPM 并了解如何構建自己的軟件包，請繼續[下一節](#authenticating-to-the-gitlab-npm-registry) . ### Installing NPM[](#installing-npm "Permalink") 按照[npmjs.com](https://s0docs0npmjs0com.icopy.site/downloading-and-installing-node-js-and-npm)上的說明下載 Node.js 和 NPM 并將其安裝到本地開發環境. 安裝完成后，通過運行以下命令驗證您可以在終端中使用 NPM： ``` npm --version ``` 您應該會在輸出中看到 NPM 版本： ``` 6.10.3 ``` ### Installing Yarn[](#installing-yarn "Permalink") 您可能需要安裝并使用 Yarn 替代 NPM. 請按照[yarnpkg.com](https://classic.yarnpkg.com/en/docs/install)上的說明在您的開發環境上進行安裝. Once installed, you can verify that Yarn is available with the following command: ``` yarn --version ``` You should see the version printed like so: ``` 1.19.1 ``` ### Creating a project[](#creating-a-project "Permalink") 了解如何創建完整的 JavaScript 項目不在本指南的范圍內，但是您可以通過創建并導航到空目錄并使用以下命令來初始化新的空包： ``` npm init ``` 或者，如果您使用的是 Yarn： ``` yarn init ``` 這將帶您解決一系列問題，以產生`package.json`文件，這是所有 NPM 軟件包所必需的. 最重要的問題是軟件包名稱. NPM 軟件包必須[遵循命名約定，](#package-naming-convention)并且范圍應限于注冊表所在的項目或組. 完成設置后，現在就可以將軟件包上傳到 GitLab 注冊表了. 首先，您需要設置身份驗證，然后將 GitLab 配置為遠程注冊表. ## Authenticating to the GitLab NPM Registry[](#authenticating-to-the-gitlab-npm-registry "Permalink") 如果項目是私有項目，或者您要將 NPM 軟件包上傳到 GitLab，則需要提供憑據進行身份驗證. 首選[個人訪問令牌](../../profile/personal_access_tokens.html)和[部署令牌](../../project/deploy_tokens/index.html) ，但支持[OAuth 令牌](../../../api/oauth2.html#resource-owner-password-credentials-flow) . **雙因素認證（2FA）僅支持個人訪問令牌：**如果你有 2FA 啟用，你需要使用一個[令牌個人訪問](../../profile/personal_access_tokens.html)使用 OAuth 標題與范圍設置為`api`或[令牌部署](../../project/deploy_tokens/index.html)與`read_package_registry`或`write_package_registry`范圍. 標準 OAuth 令牌將無法向 GitLab NPM 注冊表進行身份驗證. ### Authenticating with a personal access token or deploy token[](#authenticating-with-a-personal-access-token-or-deploy-token "Permalink") 要使用[個人訪問令牌](../../profile/personal_access_tokens.html)或[部署令牌進行](../../project/deploy_tokens/index.html)身份驗證，請設置 NPM 配置： ``` # Set URL for your scoped packages. # For example package with name `@foo/bar` will use this URL for download npm config set @foo:registry https://gitlab.com/api/v4/packages/npm/ # Add the token for the scoped packages URL. This will allow you to download # `@foo/` packages from private projects. npm config set '//gitlab.com/api/v4/packages/npm/:_authToken' "<your_token>" # Add token for uploading to the registry. Replace <your_project_id> # with the project you want your package to be uploaded to. npm config set '//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "<your_token>" ``` 將`<your_project_id>`替換為可以在項目主頁上找到的項目 ID，并將`<your_token>`替換為個人訪問令牌或部署令牌. 如果您具有自行管理的 GitLab 安裝， `gitlab.com`使用您的域名替換`gitlab.com` . 現在，您應該能夠將 NPM 軟件包下載并上傳到您的項目. **注意：**如果遇到有關[Yarn](https://classic.yarnpkg.com/en/)的錯誤消息，請參閱[故障排除部分](#troubleshooting) . ### Using variables to avoid hard-coding auth token values[](#using-variables-to-avoid-hard-coding-auth-token-values "Permalink") 為了避免對`authToken`值進行硬編碼，可以在其位置使用變量： ``` npm config set '//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "${NPM_TOKEN}" npm config set '//gitlab.com/api/v4/packages/npm/:_authToken' "${NPM_TOKEN}" ``` 然后，您可以在本地或通過 GitLab CI / CD 運行`npm publish` ： * **本地：**發布前導出`NPM_TOKEN` ： ``` NPM_TOKEN=<your_token> npm publish ``` * **GitLab CI / CD：**設置`NPM_TOKEN` [變量](../../../ci/variables/README.html)下，項目的**設置> CI / CD>變量** . ### Authenticating with a CI job token[](#authenticating-with-a-ci-job-token "Permalink") 在 GitLab Premium 12.5 中[引入](https://gitlab.com/gitlab-org/gitlab/-/issues/9104) . 如果您將 NPM 與 GitLab CI / CD 一起使用，則可以使用 CI 作業令牌代替個人訪問令牌或部署令牌. 令牌將繼承生成管道的用戶的權限. 將相應的部分添加到您的`.npmrc`文件中： ``` @foo:registry=https://gitlab.com/api/v4/packages/npm/ //gitlab.com/api/v4/packages/npm/:_authToken=${CI_JOB_TOKEN} //gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN} ``` ## Uploading packages[](#uploading-packages "Permalink") 在能夠上載軟件包之前，您需要為 NPM 指定注冊表. 為此，將以下部分添加到`package.json`的底部： ``` "publishConfig": { "@foo:registry":"https://gitlab.com/api/v4/projects/<your_project_id>/packages/npm/" } ``` 將`<your_project_id>`替換為您的項目 ID（可在項目的主頁上找到），然后將`@foo`替換為您自己的作用域. 如果您具有自行管理的 GitLab 安裝， `gitlab.com`使用您的域名替換`gitlab.com` . 啟用它并設置[身份驗證后](#authenticating-to-the-gitlab-npm-registry) ，您可以將 NPM 包上傳到您的項目中： ``` npm publish ``` 然后，您可以導航到項目的" **程序包和注冊表"**頁面，查看上載的程序包，甚至刪除它們. 如果嘗試使用給定范圍內已經存在的名稱發布程序包，則會收到`403 Forbidden!` 錯誤. ## Uploading a package with the same version twice[](#uploading-a-package-with-the-same-version-twice "Permalink") 您不能兩次上傳相同名稱和版本的軟件包，除非先刪除現有軟件包. 這與 npmjs.org 的行為保持一致，但 npmjs.org 不允許用戶多次發布同一版本，即使該版本已被刪除也是如此. ## Package naming convention[](#package-naming-convention "Permalink") **程序包的作用域必須在項目的根名稱空間中** . 程序包名稱可以是任何名稱，但最好使用項目名稱，除非由于命名沖突而無法使用. 例如： | Project | Package | Supported | | --- | --- | --- | | `foo/bar` | `@foo/bar` | Yes | | `foo/bar/baz` | `@foo/baz` | Yes | | `foo/bar/buz` | `@foo/anything` | Yes | | `gitlab-org/gitlab` | `@gitlab-org/gitlab` | Yes | | `gitlab-org/gitlab` | `@foo/bar` | No | 用于命名的正則表達式正在驗證來自所有程序包管理器的所有程序包名稱： ``` /\A\@?(([\w\-\.\+]*)\/)*([\w\-\.]+)@?(([\w\-\.\+]*)\/)*([\w\-\.]*)\z/ ``` 它允許使用大寫字母，而 NPM 不允許，并且幾乎允許 NPM 允許的所有字符，但有少數例外（不允許`~` ）. **注意：**需要大寫字母，因為要求范圍必須與項目的頂級名稱空間相同. 因此，例如，如果您的項目路徑為`My-Group/project-foo` ，則您的程序包必須命名為`@My-Group/any-package-name` . `@my-group/any-package-name`不起作用.**在更新用戶/組的路徑或傳輸（子）組/項目時：**如果使用 NPM 包更新**項目**的根名稱空間，則更改將被拒絕. 為此，請確保先刪除所有 NPM 軟件包. 不要忘記更新`.npmrc`文件以遵循上述命名約定，并在必要時運行`npm publish` . 現在，您可以配置項目以通過 GitLab NPM 注冊表進行身份驗證. ## Installing a package[](#installing-a-package "Permalink") NPM 軟件包通常使用 JavaScript 項目中的`npm`或`yarn`命令安裝. 如果尚未安裝，則需要設置作用域軟件包的 URL. 您可以使用以下命令執行此操作： ``` npm config set @foo:registry https://gitlab.com/api/v4/packages/npm/ ``` 您將需要用您的作用域替換`@foo` . 接下來，您需要確保已設置[身份驗證](#authenticating-to-the-gitlab-npm-registry) ，以便成功安裝軟件包. 完成此操作后，您可以在項目中運行以下命令來安裝軟件包： ``` npm install @my-project-scope/my-package ``` 或者，如果您使用的是 Yarn： ``` yarn add @my-project-scope/my-package ``` ### Forwarding requests to npmjs.org[](#forwarding-requests-to-npmjsorg "Permalink") [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/55344) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.9. 默認情況下，當在 GitLab NPM 注冊表中找不到 NPM 軟件包時，該請求將轉發到[npmjs.com](https://s0www0npmjs0com.icopy.site/) . 管理員可以在" [持續集成"設置中](../../admin_area/settings/continuous_integration.html)禁用此行為. ## Removing a package[](#removing-a-package "Permalink") 在項目頁面的軟件包視圖中，您可以通過單擊紅色垃圾圖標或單擊軟件包詳細信息頁面上的**刪除**按鈕來**刪除**軟件包. ## Publishing a package with CI/CD[](#publishing-a-package-with-cicd "Permalink") 要在[GitLab CI / CD 中](./../../../ci/README.html)使用 NPM 命令，可以使用`CI_JOB_TOKEN`代替個人訪問令牌或在命令中部署令牌. 一個簡單的`.gitlab-ci.yml`文件示例，用于發布 NPM 軟件包： ``` image: node:latest stages: - deploy deploy: stage: deploy script: - echo '//gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN}'>.npmrc - npm publish ``` 了解有關[使用`CI_JOB_TOKEN`驗證 GitLab NPM 注冊表的更多信息](#authenticating-with-a-ci-job-token) . ## Troubleshooting[](#troubleshooting "Permalink") ### Error running yarn with NPM registry[](#error-running-yarn-with-npm-registry "Permalink") 如果您在 NPM 注冊表中使用[yarn](https://classic.yarnpkg.com/en/) ，則可能會收到以下錯誤消息： ``` yarn install v1.15.2 warning package.json: No license field info No lockfile found. warning XXX: No license field [1/4] ?? Resolving packages... [2/4] ?? Fetching packages... error An unexpected error occurred: "https://gitlab.com/api/v4/projects/XXX/packages/npm/XXX/XXX/-/XXX/XXX-X.X.X.tgz: Request failed \"404 Not Found\"". info If you think this is a bug, please open a bug report with the information provided in "/Users/XXX/gitlab-migration/module-util/yarn-error.log". info Visit https://classic.yarnpkg.com/en/docs/cli/install for documentation about this command ``` 在這種情況下，請嘗試將其添加到您的`.npmrc`文件中（并將`<your_token>`替換為您的個人訪問令牌或部署令牌）： ``` //gitlab.com/api/v4/projects/:_authToken=<your_token> ``` ### `npm publish` targets default NPM registry (`registry.npmjs.org`)[](#npm-publish-targets-default-npm-registry-registrynpmjsorg "Permalink") 確保在`package.json`和`.npmrc`文件中一致設置了包作用域. 例如，如果您在 GitLab 中的項目名稱為`foo/my-package` ，則`package.json`文件應如下所示： ``` { "name": "@foo/my-package", "version": "1.0.0", "description": "Example package for GitLab NPM registry", "publishConfig": { "@foo:registry":"https://gitlab.com/api/v4/projects/<your_project_id>/packages/npm/" } } ``` `.npmrc`文件應如下所示： ``` //gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken=<your_token> //gitlab.com/api/v4/packages/npm/:_authToken=<your_token> @foo:registry=https://gitlab.com/api/v4/packages/npm/ ``` ### `npm install` returns `Error: Failed to replace env in config: ${NPM_TOKEN}`[](#npm-install-returns-error-failed-to-replace-env-in-config-npm_token "Permalink") 除非您的項目是私有的，否則您不需要令牌即可運行`npm install` （僅要求發布令牌）. 如果`.npmrc`文件是以`$NPM_TOKEN`的引用簽`$NPM_TOKEN` ，則可以將其刪除. 如果您希望保留參考，則需要在運行`npm install`之前設置一個值，或者使用[GitLab 環境變量](./../../../ci/variables/README.html)來設置該值： ``` NPM_TOKEN=<your_token> npm install ``` ### `npm install` returns `npm ERR! 403 Forbidden`[](#npm-install-returns-npm-err-403-forbidden "Permalink") * 檢查您的令牌是否已過期并具有適當的權限. * 檢查您是否嘗試發布名稱在給定范圍內已經存在的軟件包. * 確保作用域的軟件包 URL 包含斜杠： * 正確： `//gitlab.com/api/v4/packages/npm/` * 錯誤的： `//gitlab.com/api/v4/packages/npm` ## NPM dependencies metadata[](#npm-dependencies-metadata "Permalink") 在 GitLab Premium 12.6 中[引入](https://gitlab.com/gitlab-org/gitlab/-/issues/11867) . 從 GitLab 12.6 開始，發布到 GitLab NPM 注冊表的新軟件包向 NPM 客戶端公開了以下屬性： * name * version * dist-tags * dependencies * dependencies * devDependencies * bundleDependencies * peerDependencies * deprecated ## NPM distribution tags[](#npm-distribution-tags "Permalink") 在 GitLab Premium 12.8 中[引入](https://gitlab.com/gitlab-org/gitlab/-/issues/9425) . 您可以為新發布的軟件包添加[分發標簽](https://s0docs0npmjs0com.icopy.site/cli/dist-tag) . 它們遵循 NPM 的約定，在這些約定中它們是可選的，并且每個標簽一次只能分配給一個軟件包. 當發布沒有標簽的軟件包時，默認情況下會添加`latest`標簽. 在未指定標簽或版本的情況下安裝軟件包也是如此. 支持的`dist-tag`命令和通常使用標簽的示例： ``` npm publish @scope/package --tag # Publish new 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 ``` **警告：**由于 NPM 6.9.0 中的錯誤，刪除 dist 標簽失敗. 確保您的 NPM 版本大于 6.9.1.