Monorepo包中Next.js <Image/>与<Link/>组件使用问题排查

错误原因分析 #

• 多Next.js实例冲突：peerDependencies仅声明依赖版本要求，若my-organization/ui包在devDependencies中也安装了Next.js，或monorepo依赖管理未正确共享Next.js实例，会导致消费应用与UI包各自加载一个Next.js副本。Next.js的<Image/>、<Link/>等组件依赖单例环境，多实例下组件会被识别为object而非预期的组件类型，触发错误。
• 未转译的模块语法：若UI包使用ES模块语法（如import/export）但未预编译为Next.js兼容格式，Next.js默认不会转译node_modules中的包，导致无法正确解析组件，进而抛出类型错误。

无需transpilePackages的优化方案 #

1. 严格控制Next.js依赖实例

   • 确保my-organization/ui的package.json仅在peerDependencies中声明Next.js，移除devDependencies中的Next.js依赖。
   • 若使用pnpm/Yarn Workspaces等monorepo工具，配置依赖共享，让所有包共用根目录的Next.js实例：

     // ui包的package.json
     {
       "peerDependencies": {
         "next": "^13.x || ^14.x"
       },
       "devDependencies": {
         // 移除next的直接依赖，通过workspace共享根依赖
       }
     }
     

2. 预编译UI包为兼容格式

   • 使用TypeScript或Babel将UI包编译为同时支持CommonJS和ES模块的格式，在package.json中配置对应导出字段：

     // ui包的package.json
     {
       "main": "./dist/cjs/index.js",
       "module": "./dist/esm/index.js",
       "types": "./dist/types/index.d.ts",
       "files": ["dist"]
     }
     

   • 添加编译脚本，确保发布前生成dist目录：

     {
       "scripts": {
         "build": "tsc --project tsconfig.cjs.json && tsc --project tsconfig.esm.json"
       }
     }
     

3. 合并重复依赖实例

   • 在消费应用中执行包管理工具的dedupe命令，合并多个Next.js实例：

     pnpm dedupe next
     # 或
     yarn dedupe next
     

补充说明 #

若使用TurboRepo等monorepo构建工具，可配置管道任务确保UI包先完成编译，再被消费应用引用，进一步规避模块解析问题。

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