如何配置npm实现类似Yarn Classic的依赖扁平化效果？

我们团队多数项目使用npm，但有一个私有模块依赖Yarn Classic的强扁平化特性——Yarn会将所有可提升的依赖移至根目录，而npm默认的扁平化策略更保守，导致npx失效，子模块只能通过完整路径访问依赖。

依赖结构对比 #

npm生成的node_modules结构：

% npm list ajv
cdk@0.1.0 /home/me/git/example
└─┬ example@1.1
  └─┬ aws-cdk-lib@2.154.1
    └─┬ table@6.8.2
      └── ajv@8.16.0

Yarn Classic生成的node_modules结构：

% npm list ajv
cdk@0.1.0 /home/me/git/example
├─┬ example@1.1
│ └─┬ aws-cdk-lib@2.154.1
│   └─┬ table@6.8.2
│     └── ajv@8.16.0
├── ajv@8.17.1 extraneous
└─┬ table@6.8.2 extraneous
  └── ajv@8.17.1 deduped

已尝试但无效的方案 #

• npm install --legacy-peer-deps
• npm install --prefer-dedupe
• npm dedupe
• npm install --install-strategy=hoisted（及nested、shallow、linked）
• 在package.json中添加"flat": true

可行解决方案 #

1. 配置npm强制全量提升依赖

在项目根目录创建/修改.npmrc文件，添加以下配置：

hoist=true
hoist-pattern=**

该配置会让npm尽可能将所有子依赖提升至根目录，接近Yarn Classic的扁平化效果。执行npm install重新安装依赖即可生效。

2. 用overrides强制统一依赖版本

如果子依赖存在版本差异导致无法提升，可在package.json中通过overrides字段强制所有依赖树使用指定版本：

{
  "overrides": {
    "ajv": "8.17.1",
    "table": "6.8.2"
  }
}

这样npm会将指定版本的依赖直接安装在根目录，彻底避免嵌套问题，同时保证依赖版本统一。

3. 结合npm dedupe与安装策略

执行以下命令组合，先优先合并版本再强制整理依赖结构：

npm install --install-strategy=hoisted --prefer-dedupe
npm dedupe --force

--prefer-dedupe会优先合并相同版本的依赖，npm dedupe --force会强制重新梳理依赖树，尽可能将依赖提升到根目录。

注意事项 #

• 上述方案基于npm v7及以上版本，执行前可通过npm -v确认版本符合要求。
• 使用overrides时需验证版本兼容性，避免强制指定不兼容版本导致项目报错。

内容的提问来源于stack exchange，提问作者git_driver