如何解决安装Next.js+Preact时的npm ERESOLVE依赖冲突问题

npm ERR! code ERESOLVE报错是两层因素叠加导致的：

• 官方Next.js Preact示例的配置逻辑是通过npm包名别名，把项目里的react、react-dom包直接指向@preact/compat兼容层，npm解析时会把@preact/compat自身的版本号识别为替换后的react包版本，也就是报错里显示的react@0.0.3，这个版本号完全不在Next.js 10.0.6要求的peer依赖范围react@^16.6.0 || ^17内
• 本地使用的npm为7及以上版本，默认开启严格的依赖树校验，遇到这类别名替换导致的版本不匹配，会直接中断安装流程，不会像npm 6版本那样自动兼容调整
• 这类冲突和项目本身无关，只要是手动配置Preact兼容层替换React的场景，基本都会触发相同的报错逻辑

快速跑通官方示例 #

直接在初始化命令中传入参数，绕过npm的严格peer依赖校验：

npx create-next-app --example using-preact using-preact-app -- --legacy-peer-deps

注意：npx场景下需要用--做参数分隔，否则--legacy-peer-deps会被create-next-app命令拦截，不会传递给底层的npm install流程。

项目创建完成后，可以在项目根目录新建.npmrc文件，写入配置：

legacy-peer-deps=true

后续在项目内执行所有npm命令都会自动跳过严格peer校验，不需要每次手动加参数。

手动搭建Preact+Next.js环境 #

如果需要自定义配置项目结构，不要直接拉取示例模板，可以按照以下步骤操作：

1. 新建项目文件夹，在文件夹内执行npm初始化：

   npm init -y
   

2. 安装依赖时带上跳过校验的参数，直接通过别名指向Preact兼容层，不需要安装原版React：

   npm install next@^10.0.0 preact react@npm:@preact/compat react-dom@npm:@preact/compat --legacy-peer-deps
   

3. 打开项目的package.json，补充基础运行脚本和别名映射配置：
   • 在scripts字段新增三个核心命令：

     "scripts": {
       "dev": "next dev",
       "build": "next build",
       "start": "next start"
     }
     

   • 新增browser字段写死模块解析规则，确保打包流程能正确识别Preact兼容层：

     "browser": {
       "react": "preact/compat",
       "react-dom": "preact/compat"
     }
     

• 尽量不要用报错提示的--force参数替代*--legacy-peer-deps*，前者会强制覆盖依赖版本，可能导致后续运行时出现难以定位的模块解析异常，后者仅跳过peer依赖的版本校验，不会改动实际安装的包内容
• 报错中提到的Found: react@0.0.3是@preact/compat包自身的发布版本号，不是真的安装了一个无意义的0.0.3版本React，不需要额外调整react的版本号配置
• 如果后续切换到pnpm作为包管理工具，需要在项目根目录配置对应的别名替换规则，pnpm同样有严格的peer依赖校验逻辑，默认不会支持这类包名替换的操作

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