yarn配置文件(.yarnrc和.yarnrc.yml)

Yarn的配置文件主要涉及.yarnrc和.yarnrc.yml两种格式‌，用于自定义Yarn的行为和依赖管理策略。

.yarnrc 文件（旧版）用于配置Yarn的旧版本（如Yarn 1.x）的行为，支持简单的键值对格式。

`.yarnrc.yml` 文件（新版，推荐）

Yarn 2+ 推荐使用YAML格式的配置文件，支持更复杂的结构化配置。

yarnPath：指定Yarn二进制文件的路径（用于Berry版本）。
nodeLinker：设置依赖链接方式（node-modules或pnp）。
npmRegistryServer：自定义npm仓库地址。
plugins：加载Yarn插件。

配置优先级

Yarn会按以下顺序加载配置（后加载的覆盖前者）：

默认配置（Yarn内置）。
全局配置文件（如~/.yarnrc或~/.yarnrc.yml）。
项目本地配置文件（项目根目录下的.yarnrc或.yarnrc.yml）。

验证配置

通过以下命令检查当前生效的配置：

yarn config list

迁移指南

如果从旧版Yarn升级到Berry（Yarn 2+），需运行以下命令生成初始配置：

yarn set version berry

这会生成.yarnrc.yml并初始化Plug'n'Play（PnP）环境。

以下是我们在项目中经常用到的.yarnrc.yml配置。

yarnPath

`yarnPath: .yarn/releases/yarn-3.6.2.cjs` 表示项目使用的 Yarn 包管理器的特定版本（3.6.2），并且这个版本的可执行文件位于项目的 `.yarn/releases/` 目录下。这通常用于确保项目在不同环境中使用相同的 Yarn 版本，以避免潜在的兼容性问题。

要生成 `.yarn/releases/yarn-3.6.2.cjs`，可以使用以下步骤：

在你的项目根目录下，使用以下命令指定你想要的 Yarn 版本（例如 3.6.2）：

yarn set version 3.6.2

执行上述命令后，Yarn 会自动下载指定版本并将其保存到 `.yarn/releases/` 目录下，生成 `yarn-3.6.2.cjs` 文件。

可以查看 `.yarn/releases/` 目录，确认文件是否存在。这样，你就成功生成了指定版本的 Yarn 可执行文件。

nodeLinker

nodeLinker 用于控制 Yarn 如何解析和链接依赖。Yarn 提供了两种 nodeLinker 模式：node-modules 和 plugins。

‌node-modules‌：这是默认模式，类似于 npm 的 node_modules 结构。
‌plugins‌：使用 PnP (Plug'n'Play) 技术，可以提高性能和兼容性。

可以这样配置：

nodeLinker: node-modules
nodeLinker: pnp

如果使用的是 Yarn 的新版本（例如 Yarn 2+），PnP 应该已经是默认的 nodeLinker 设置。如果需要手动设置，可以参考上面的命令行示例进行调整。

unsafeHttpWhitelist

`unsafeHttpWhitelist` 用于指定哪些 HTTP 源可以被 Yarn 访问，以防止安全风险。

默认情况下，Yarn 只允许使用 HTTPS 进行包的下载，添加不安全的 HTTP 源时，可以将其列入白名单。这在某些情况下是有用的，比如在本地开发环境中或者在测试环境中，当你需要绕过 HTTPS 的限制时。

unsafeHttpWhitelist:
  - "http://example.com"
  - "http://another-example.com"

在这个例子中，Yarn 将允许从 `http://example.com` 和 `http://another-example.com` 下载包，即使它们是 HTTP 而非 HTTPS。

然而，需要注意的是，通过 HTTP 而不是 HTTPS 可能会导致安全风险，因为它不提供加密保护，使得数据容易被窃听或篡改。

npmRegistryServer

如果你需要指定一个 npm 仓库服务器（例如，使用私有 npm 仓库），你可以这样设置：

npmRegistryServer: "https://your-private-registry.com"

这里的 `npmRegistryServer` 是全局配置，适用于所有包的注册表。而 `npmScopes` 下的 `npmRegistryServer` 是针对特定作用域的配置，只影响该作用域内的包。这样可以实现不同作用域使用不同的注册表。

npmPublishRegistry

用于指定 Yarn 发布包时的默认注册表地址。它影响以下方面：

包发布：当你使用 `yarn publish` 命令时，Yarn 会将包发布到指定的注册表。
简化配置：可以避免在每次发布时手动指定注册表，提升工作效率。
统一管理：适用于团队项目，确保所有成员使用相同的发布注册表。

这里的 `npmPublishRegistry` 是全局配置，用于指定所有包的发布注册表。而 `npmScopes` 下的 `npmPublishRegistry` 是针对特定作用域的配置，仅影响该作用域内的包发布。这样可以实现不同作用域使用不同的发布注册表。

package.json 的 publishConfig 和 .yarnrc.yml的npmPublishRegistry 有什么区别

它们都与包的发布相关，但它们的作用和使用场景不同。

publishConfig用于指定包的发布配置，包括发布的注册表、访问权限等。

{
    "publishConfig": {
      "registry": "https://custom-registry.com/"
    }
}

npmPublishRegistry用于全局或项目级别配置 Yarn 的 npm 注册表设置，影响所有通过 Yarn 发布的包。

npmPublishRegistry: "https://custom-registry.com/"

主要区别

作用范围

`publishConfig` 是针对特定包的配置。
`npmPublishRegistry` 是全局或项目级别的配置。

优先级

如果在 `publishConfig` 中指定了 `registry`，它会优先于 `.yarnrc.yml` 中的设置。

适用性

`publishConfig` 更加灵活，适合于单个包的定制。
`.yarnrc.yml` 的设置适用于整个项目，便于统一管理。

总结来说，使用 `publishConfig` 可以为每个包单独配置，而 `.yarnrc.yml` 提供了一种全局配置的方式。

npmScopes

npm范围（Scopes）通常用于私有包或者组织内部的包管理。在yarnrc.yml中配置npm范围可以帮助Yarn正确解析和安装这些包。

npmScopes:
  my-scope:
    npmAlwaysAuth: true
    npmRegistryServer: "http://localhost:4873"
    npmPublishRegistry: "http://localhost:4873"
    npmAuthIdent: "username:password"
    npmAuthToken: "xxxxxxxxxxx"

在 `npmScopes` 的配置中，各个参数的含义如下：

myscope: 作用域名称，通常用于组织或项目的包。在这个例子中，名称为@my-scope。
npmAlwaysAuth: 设置为 `true` 时，Yarn 会在每次请求时始终使用身份验证。这对于私有仓库非常重要，以确保每次访问都经过授权。
npmRegistryServer: 指定用于安装该作用域下包的注册服务器的 URL。在这个例子中，使用的是本地的私有注册服务。
npmPublishRegistry: 指定用于发布该作用域下包的注册服务器的 URL。在这个例子中，使用的是本地的私有注册服务。
npmAuthToken: 用于身份验证的令牌，通常是访问私有注册服务器所需的 API token。
npmAuthIdent: 用于身份验证的字符串，通常是 `username:password` 格式。

在这个示例中，所有 `@my-scope` 作用域下的包都将使用指定的本地注册服务器进行下载和发布，并始终进行身份验证。

npmAuthToken如何获取？

1、登录私有仓库：

npm login --registry=http://localhost:4873

2、获取token

在`~/.npmrc` 文件中保存了正确的认证信息：

//localhost:4873/:_authToken="<yourToken>"

把这里_authToken的值复制给npmAuthToken赋值就可以了。

package.json 的 publishConfig 和 .yarnrc.yml npmScopes下的 npmPublishRegistry 有什么区别

作用范围

package.json` 的 `publishConfig`：仅适用于该特定包（例如：`@scope/aaa`），可以指定该包的发布目标和其他发布选项。
`.yarnrc.yml` 的 `npmScopes` 下的 `npmPublishRegistry`：适用于该作用域下的所有包（如 `@scope/*`），提供一个统一的发布注册表配置。

优先级

如果在 `package.json` 中设置了 `publishConfig`，该配置会覆盖 `.yarnrc.yml` 中的作用域配置。
如果 `package.json` 中没有设置 `publishConfig`，则会使用 `.yarnrc.yml` 中的 `npmPublishRegistry` 作为默认发布注册表。

所以，`publishConfig` 是包级别的配置，`npmPublishRegistry` 是作用域级别的全局配置，优先级上 `publishConfig` 高于全局配置。

plugins

Yarn插件可以扩展Yarn的功能，例如添加新的命令或者修改现有命令的行为。在yarnrc.yml中配置插件可以让这些插件在项目中使用。

plugins:
  - path: .yarn/plugins/@yarnpkg/plugin-workspace-tools.cjs
    spec: "@yarnpkg/plugin-workspace-tools"
  - path: .yarn/plugins/@yarnpkg/plugin-interactive-tools.cjs
    spec: "@yarnpkg/plugin-interactive-tools"

要下载这些 Yarn 插件，您可以按照以下步骤操作：

1. 确保使用 Yarn 2 或更高版本: 这些插件适用于 Yarn 的新版本。
2. 在项目根目录下创建或更新 `.yarnrc.yml` 文件: 这个文件应包含您要使用的插件配置。
3. 使用 Yarn 安装插件:

yarn plugin import @yarnpkg/plugin-workspace-tools
yarn plugin import @yarnpkg/plugin-interactive-tools

运行以下命令查看已安装的插件：

yarn plugin list

这将确保您成功下载并安装所需的插件。

在`.yarn/plugins` 目录用于存放这些插件，所有安装的插件会被存放在 `.yarn/plugins` 目录中。

packageExtensions

用于扩展或修改已安装依赖包的行为。通过这个配置，用户可以添加额外的依赖、修改版本要求或进行其他定制。

自动安装缺失依赖

假设你有一个项目依赖于 `example-package`，但该包缺少一个必要的依赖 `missing-dependency`。

可以在 `.yarnrc.yml` 中这样配置：

packageExtensions:
  example-package@*:
    dependencies:
      missing-dependency: ^1.0.0

当安装 `example-package` 时，Yarn 会自动安装 `missing-dependency`，也可以为`missing-dependency`强制指定某个依赖的版本，确保兼容性。

定制构建过程

假设你使用的 `example-package` 需要一个构建工具 `build-tool`，但该工具没有在 `example-package` 的依赖中列出。你希望在安装时自动添加它，并确保它在构建时执行。

packageExtensions:
  example-package@*:
    dependencies:
      build-tool: ^2.0.0

通过 `dependencies` 自动安装 `build-tool`，确保它在项目中可用。

如果 `example-package` 提供了钩子（如 `postinstall`），可以在项目的 `package.json` 中定义一个脚本，该脚本依赖于 `build-tool`。

yarn报错 error An unexpected error occurred

yarn报错 error An unexpected error occurred: “https://registry.yarnpkg.com… connect ETIMEDOUT 104.16.19.35:443”，报错原因

资源地址请求超时造成的，需要更换一下请求地址。

解决方案

资源地址设置为淘宝镜像：

yarn config set registry https://registry.npm.taobao.org/

查看当前镜像

yarn config get registry

重新执行yarn命令下载依赖即可。

posted @ 2025-10-12 11:07 李小菜丶阅读(42) 评论(0) 收藏举报

刷新页面返回顶部

李小菜