PNPM Turborepo Monorepo中NextJS构建本地依赖路径别名冲突

问题背景 #

基于Turborepo模板搭建PNPM Monorepo，包含Next.js应用和本地共享包ui-shared。ui-shared单独构建可成功完成，但Next.js应用构建时，会因共享包内的路径别名@/utils/clsxm解析失败报错。

共享包配置详情 #

单独构建成功日志 #

ESM ⚡️ Build success in 112ms
ESM dist/index.mjs 220.69 KB
DTS Build start
DTS ⚡️ Build success in 4792ms

package.json 核心片段 #

{
  "main": "./src/index.ts",
  "module": "./dist/index.mjs",
  "types": "./src/index.ts",
  "scripts": {
    "lint": "eslint *.ts*",
    "build": "tsup ./src/index.ts --format esm,cjs --dts --external react",
    "dev": "tsup ./src/index.ts --format esm,cjs --watch --dts --external react"
  }
}

tsconfig.json 配置 #

{
  "extends": "tsconfig/react-library.json",
  "compilerOptions": {
    "baseUrl": ".",
    "resolveJsonModule": true,
    "allowJs": true,
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": ["**/*.ts", "**/*.tsx"],
  "exclude": ["dist", "build", "node_modules"]
}

Next.js 构建报错信息 #

执行pnpm build时的错误输出：

pnpm build

> @company/business-frontend@1.0.0 build /work/company/monorepo/apps/business
> next build

See more info here: https://nextjs.org/docs/messages/invalid-next-config
info  - Skipping linting
info  - Checking validity of types .Failed to compile.

../../packages/ui-shared/src/components/AnimatedLoadingMedia.tsx:9:23
Type error: Cannot find module '@/utils/clsxm' or its corresponding type declarations.

   7 | } from "react";
   8 | 
>  9 | import { clsxm } from "@/utils/clsxm";
     |                       ^
  10 | 
  11 | type AnimatedLoadingMediaProps = {
  12 |   isVideo: boolean;

> Build error occurred
Error: Call retries were exceeded
    at ChildProcessWorker.initialize (/work/company/monorepo/node_modules/.pnpm/next@12.2.4_twoewwu6sg7cdf3ao6njtbftne/node_modules/next/dist/compiled/jest-worker/index.js:1:11661)
    at ChildProcessWorker._onExit (/work/company/monorepo/node_modules/.pnpm/next@12.2.4_twoewwu6sg7cdf3ao6njtbftne/node_modules/next/dist/compiled/jest-worker/index.js:1:12599)
    at ChildProcess.emit (node:events:390:28)
    at Process.ChildProcess._handle.onexit (node:internal/child_process:290:12) {
  type: 'WorkerError'
}

Next.js 应用 tsconfig.json 配置 #

{
  "extends": "tsconfig/nextjs.json",
  "compilerOptions": {
    "lib": [
      "dom",
      "dom.iterable",
      "esnext"
    ],
    "allowJs": true,
    "baseUrl": ".",
    "module": "esnext",
    "paths": {
      "@/*": ["src/*"],
      "@": ["src"],
      "@public/*": ["public/*"],
      "@public": ["public"]
    }
  },
  "include": [
    "next-env.d.ts",
    "**/*.ts",
    "**/*.tsx"
  ],
  "exclude": [
    "node_modules"
  ]
}

问题核心原因 #

Next.js构建时会直接处理共享包的源码，而非消费其已构建的产物。此时共享包内的@/*路径别名仅在自身tsconfig中生效，Next.js的tsconfig无法识别该别名规则，导致解析失败。

解决方案 #

方案1：让Next.js直接消费共享包构建产物 #

修改共享包的package.json，将入口和类型指向dist目录的编译产物：

{
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts"
  // 保留其他原有配置
}

同时在根目录或共享包目录的.npmrc中添加：

shamefully-hoist=true

确保依赖解析正常。

方案2：在Next.js中扩展共享包的路径别名 #

在Next.js的tsconfig.json中添加共享包的路径映射，让Next.js识别共享包内的@/*规则：

{
  "compilerOptions": {
    // 原有配置
    "paths": {
      "@/*": ["src/*", "../../packages/ui-shared/src/*"],
      "@public/*": ["public/*"],
      "@public": ["public"]
    }
  }
}

方案3：用Turborepo管道强制先构建共享包 #

在根目录的turborepo.json中配置构建依赖顺序，确保Next.js构建前先完成ui-shared的构建：

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    }
  }
}

方案4：配置Next.js转译共享包 #

在Next.js的next.config.js中添加transpilePackages，指定转译ui-shared，同时确保共享包已提前构建：

/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['ui-shared'],
}

module.exports = nextConfig

内容的提问来源于stack exchange，提问作者Nikola-Milovic