blog.dopana

返回

你是否想知道为什么一些项目的根目录中有.npmrc文件?或者如何为你的公司配置私有注册表?.npmrc文件是控制npm、pnpm、yarn和Bun等包管理器行为的关键。

在这篇文章中,我们将探讨.npmrc如何工作,特别是使用Bun时——一个新的超快速包管理器。

为什么.npmrc很重要#

想象一下,你正在使用公司私有包的项目中工作。如果每次运行npm install或bun install都必须输入用户名和密码,那将非常令人沮丧。.npmrc通过集中存储配置来解决这个问题。

[!NOTE] .npmrc作为包管理器的配置文件,类似于.env用于环境变量,但专门用于npm/Bun。

.npmrc是什么?#

.npmrc是一个键值对配置文件,用于设置包管理器(npm、pnpm、yarn、Bun)的选项。它可以包含:

  • 注册表URL(从哪里下载包)
  • 身份验证令牌(访问私有注册表)
  • 安装设置,如save-exact、engine-strict等

.npmrc的优先级顺序#

包管理器在多个位置查找.npmrc文件,按优先级从低到高排序:

Default npmGlobal/etc/npmrcUser~/.npmrcProject./.npmrcCLI/EnvironmentNPM_CONFIG_REGISTRY

这意味着:

  • Default: npm的内置默认值
  • Global: 系统级文件(通常是/etc/npmrc)
  • User: 主目录中的用户级文件(~/.npmrc)
  • Project: 项目根目录中的本地文件(./.npmrc)- 你应该在这里配置项目特定设置
  • CLI/Environment: 命令行标志或环境变量(最高优先级)

[!TIP]

  • 如果相同的配置出现在多个位置,优先级较高的会覆盖优先级较低的。

Bun如何处理.npmrc#

Bun的优势之一是它与标准.npmrc文件完全兼容。你可以在现有的Node.js项目中直接使用Bun,而无需更改注册表或身份验证设置。

Bun支持的设置#

Bun支持常见的.npmrc指令,包括:

  • 注册表URL: 配置默认注册表和作用域注册表
  • 作用域注册表: 为特定作用域分配特定注册表(例如@mycompany)
  • 身份验证令牌: _authToken、_auth、username、_password、email
  • 项目选项: save-exact=true、link-workspace-packages

Bunfig.toml - Bun的原生替代方案#

Bun也有自己的原生配置文件bunfig.toml,但它继续尊重.npmrc以实现跨工具兼容性。

[!WARNING]

  • 如果你同时使用.npmrc和bunfig.toml,请确保它们不会以冲突的方式配置相同的内容。

实际示例#

基本配置#

.npmrc
# 使用默认注册表
registry=https://registry.npmjs.org

# 始终保存确切的版本号(无^或~前缀)
save-exact=true
ini

使用私有注册表的配置#

.npmrc
# 为公司作用域配置注册表
@mycompany:registry=https://npm.mycompany.com

# 公司注册表的身份验证令牌
//npm.mycompany.com:_authToken=${NPM_TOKEN}

# 其他包的默认注册表
registry=https://registry.npmjs.org
ini

GitHub Packages的配置#

.npmrc
# GitHub Packages注册表
@your-org:registry=https://npm.pkg.github.com

# 用于身份验证的GitHub令牌
//npm.pkg.github.com:_authToken=${GITHUB_TOKEN}
ini

GitLab Package Registry的配置#

.npmrc
# GitLab Package Registry
@your-group:registry=https://gitlab.com/api/v4/projects/PROJECT_ID/packages/npm/

# GitLab令牌
//gitlab.com/api/v4/projects/PROJECT_ID/packages/npm/:_authToken=${GITLAB_TOKEN}
ini

在Bun中使用#

当你的项目中有.npmrc文件时,Bun在运行bun install时会自动读取它:

# Bun将读取.npmrc并应用配置
bun install

# 查看当前Bun配置
bun pm config
bash

为什么要使用save-exact=true?#

当启用save-exact=true时,包管理器会在package.json中保存确切的版本,而不是使用范围(如^1.2.3或~1.2.3)。

优点:

  • 确保团队中的每个人都安装相同的版本
  • 避免包发布不兼容更新时的破坏
  • 生产环境中可预测的依赖关系

缺点:

  • 必须手动更新依赖项
  • 不会自动获取补丁更新

CI/CD中的配置#

在CI/CD环境中,通常使用环境变量而不是将令牌提交到文件:

.github/workflows/ci.yml
env:
  NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
yaml
.npmrc
# 令牌将从环境变量替换
//npm.mycompany.com:_authToken=${NPM_TOKEN}
ini

查看活动配置#

要查看正在使用哪个.npmrc文件:

# 使用npm
npm config list

# 使用Bun
bun pm config
bash

实用技巧#

  1. 始终使用项目级.npmrc进行项目特定配置
  2. 永远不要将令牌提交到git - 改用环境变量
  3. 为公司的私有包使用作用域注册表
  4. 遇到身份验证错误时检查配置
  5. 阅读私有注册表的文档(GitHub、GitLab、Azure Artifacts)

结论#

.npmrc是管理包管理器在项目中行为的重要工具。有了Bun的支持,你可以继续使用此文件,而从npm切换到Bun时无需更改配置。

了解优先级顺序和配置方法将帮助你在未来避免许多身份验证和依赖管理问题。

References#