Yarn Berry 中 package.json 格式化问题的分析与解决方案

问题背景

在 Yarn Berry 项目中，用户发现了一个关于 package.json 文件格式化的特殊现象：即使 yarn install 命令没有对 package.json 文件内容进行任何实质性修改，Yarn 仍然会重新格式化该文件。这种自动格式化行为在某些情况下可能带来不便，特别是当开发者已经对文件进行了特定的格式化配置时。

问题重现

通过以下步骤可以重现这个问题：

1. 创建一个新项目并初始化 Yarn
2. 添加一些开发依赖
3. 在 package.json 中添加特定的 ESLint 配置，特别是包含长数组的部分
4. 再次运行 yarn install

此时可以观察到，即使没有实际修改 package.json 的内容，Yarn 仍然会重新格式化文件中的数组部分，将其从单行格式改为每行一个元素的格式。

技术分析

Yarn 的核心团队认为这不是一个 bug，而是设计上的选择。Yarn 在写入 package.json 文件时会应用自己的格式化逻辑，而不是保留原有的格式。这种行为有以下几点考虑：

1. 一致性：确保所有项目中的 package.json 格式一致
2. 可读性：对于长数组或对象，分行显示通常更易于阅读
3. 简化实现：避免复杂的格式保留逻辑可以保持代码简洁

然而，这种设计确实可能干扰开发者已有的格式化配置，特别是当项目使用了如 Prettier 等格式化工具时。

解决方案

对于希望保持原有格式的开发者，有以下几种解决方案：

1. 使用 --immutable 标志

运行 yarn install --immutable 可以阻止 Yarn 修改 package.json 文件。但这种方法只适用于不需要更新依赖的情况。

2. 创建 Yarn 插件

开发者可以创建一个自定义 Yarn 插件，在安装完成后自动运行 Prettier 来恢复原有格式。以下是一个示例插件实现：

import { cwd as cwdFunc, stdout, stdin, stderr } from 'process';
import { Configuration, Hooks, Project, scriptUtils } from '@yarnpkg/core';
import { getPluginConfiguration } from '@yarnpkg/cli';
import { PortablePath } from '@yarnpkg/fslib';

module.exports = {
  factory: (): { hooks: Hooks } => ({
    hooks: {
      afterAllInstalled(project: Project): void {
        void (async () => {
          const cwd = cwdFunc() as PortablePath;
          const configuration = await Configuration.find(cwd, getPluginConfiguration());
          const { locator } = await Project.find(configuration, cwd);
          const packageAccessibleBinaries = await scriptUtils.getPackageAccessibleBinaries(
            locator,
            { project }
          );
          
          if (!packageAccessibleBinaries.get('prettier')) {
            throw new Error('Prettier not found.');
          }
          
          const ret = await scriptUtils.executePackageAccessibleBinary(
            locator,
            'prettier',
            ['--log-level', 'error', '-w', 'package.json', '.yarnrc.yml'],
            { cwd, packageAccessibleBinaries, project, stderr, stdin, stdout }
          );
          
          if (ret !== 0) {
            throw new Error(`Prettier returned non-zero: ${ret}.`);
          }
        })();
      },
    },
  }),
  name: 'plugin-prettier-after-all-installed',
};

3. 使用 Git 钩子验证

对于使用 Git 的项目，可以设置 pre-commit 钩子来验证 yarn.lock 是否与 package.json 同步，而不受格式变化的影响：

repos:
  - hooks:
      - entry: yarn install --check-cache --immutable
        files: ^package\.json$
        id: yarn-check-lock
        language: system
        name: check yarn.lock is up-to-date
        pass_filenames: false

最佳实践建议

1. 明确格式化责任：在团队中明确是使用 Yarn 的自动格式化还是统一使用 Prettier 等工具
2. 文档记录：在项目文档中记录格式化策略，避免团队成员困惑
3. CI/CD 集成：在持续集成流程中加入格式检查，确保一致性
4. 考虑使用 .yarnrc.yml：某些配置可以放在 .yarnrc.yml 中，减少对 package.json 的依赖

总结

Yarn Berry 对 package.json 的自动格式化行为是其设计的一部分，虽然可能不符合所有开发者的预期，但通过合理的配置和工具链整合，开发者可以找到适合自己的解决方案。理解工具的行为并适当调整工作流程，是高效使用现代 JavaScript 工具链的关键。