Help us learn about your current experience with the documentation. Take the survey.

npm 包发布指南

GitLab 使用 npm 包来提高项目和跨项目的代码复用性和模块化。本文概述了安全地将 npm 包发布到 npmjs.com 的最佳实践和指南。

遵循这些指南，我们可以确保 NPM 包的安全可靠发布，促进 GitLab 生态系统中的信任和一致性。

设置 npm 账户

在 npmjs.com 创建账户时，使用您的 GitLab 企业邮箱 ID。
启用 双因素认证 (2FA) 以增强安全性。
通过 issue 向直接负责的团队沟通任何账户变更（例如，邮箱更新、所有权转移）。

发布包的指南

安全性和所有权

如果使用 npm 别名，请验证别名引用的包是合法且安全的。您可以通过运行 npm info <yourpackage> alias 来验证给定别名指向的内容。确保您确信所有别名都指向您信任的合法包。
通过在 GitLab 项目中启用以下功能，避免将机密信息发布到 npm 注册表（例如，npmjs.com、GitLab npm registry 等）：
- Secret push protection
- Secret detection
保护用于注册表交互的 NPM 令牌：
- 强烈建议使用 OpenBao 或 Vault 等外部密钥存储
- 至少，将令牌安全地存储在 GitLab CI/CD 管道的环境变量中，确保启用了遮蔽和保护功能。
- 不要将令牌存储在本地计算机的不安全位置。相反，将令牌存储在 1Password 中，并避免将这些机密信息存储在未加密的文件中，如 shell 配置文件、.npmrc 和 .env。
将 gitlab-bot 添加为包的作者。这确保了在团队成员离职期间邮箱失效时，组织仍保留所有权。

依赖完整性

使用 锁定文件（package-lock.json 或 yarn.lock）来确保跨环境依赖的一致性。
考虑执行依赖锁定/规范来锁定特定版本，防止意外升级到恶意或有漏洞的版本。这可能会使依赖升级变得更加复杂。
在 CI/CD 管道中使用 npm ci（或 yarn install --frozen-lockfile）而不是 npm install，以确保依赖项按照锁定文件中的定义精确安装。
运行 untamper-my-lockfile 以保护锁定文件的完整性。

强制仅通过 CI/CD 发布

包必须仅通过受保护分支上的 GitLab CI/CD 管道发布，而不是从本地开发人员机器发布。这确保了：

机密信息得到安全管理
团队成员之间的交接是无缝的，因为工作流程是文档化和自动化的。
意外泄露或未授权发布的风险降至最低。

要设置通过 GitLab CI/CD 发布：

在 .gitlab-ci.yml 中配置一个用于发布包的作业。下面提供了一个示例
安全地存储 NPM 令牌。这可能看起来像使用 OpenBAO 或 Vault 等外部密钥存储工具。作为最后手段，使用启用了遮蔽和保护的 GitLab CI/CD 变量。
确保管道在发布前包含机密检测和代码质量检查的步骤。

安全的注册表访问

使用作用域包（@organization-name/package-name）来防止其他用户的命名空间污染或域名抢注。
限制注册表权限：
- 使用组织特定的 NPM 作用域，并强制执行访问或发布包的权限。

保护包元数据

避免在 package.json 文件中暴露敏感信息：
- 确保不包含任何机密信息或内部 URL（例如，私有 API 端点）。
- 限制 package.json 中的 files，只明确包含发布包中必要的文件。
如果包不打算公开，请使用 publishConfig.access: 'restricted' 控制可见性。

示例 CI/CD 配置

下面是一个用于发布 NPM 包的 .gitlab-ci.yml 配置示例。此代码块不打算直接使用，需要根据您的配置进行更改。这意味着您需要修改下面的示例，以包含您的 npmjs 发布令牌的位置。

stages:
  - test
  - build
  - deploy

test:
  stage: test
  image: node:22
  script:
    - npm ci
    - npm test

build:
  stage: build
  image: node:22
  script:
    - npm ci
    - npm run build

publish:
  stage: deploy
  image: node:22
  script:
    - npm ci
    - npm run build
    - npm publish
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

包安全的最佳实践

启用 npm 包发布的 2FA 以防止未授权发布。
在项目上启用 GitLab 依赖扫描并定期审查漏洞报告。
监控已发布的包是否有异常活动或未授权的更新。
在 README.md 中记录包的目的和范围，以确保与用户清晰沟通。

安全包名称示例

unique-package：不特定于 GitLab 的通用包。
existing-package-gitlab：带有 GitLab 特定修改的分支包。
@gitlab/specific-package：为内部 GitLab 使用而开发的包。

避免本地机密和手动发布

应避免手动工作流程，以确保：

机密信息保持安全：令牌和其他敏感信息应仅存在于安全的 CI/CD 环境中。
工作流程一致且可审计：CI/CD 管道确保所有发布步骤都是可重复和文档化的。
降低复杂性：集中的 CI/CD 管道简化了项目交接并最小化了风险。