NextJS pnpm workspace下无法解析外部包tsconfig路径别名模块

问题根因 #

Next.js 构建阶段默认只会解析自身应用目录下tsconfig.json（含其继承链上的配置）中定义的路径别名规则。就算开了experimental.externalDir允许引入外部workspace目录的代码，它也不会主动去读外部子包独立tsconfig里配的paths映射，webpack找不到别名对应的实际文件路径，直接就抛模块找不到的错误。这个问题和用pnpm还是yarn管理workspace没关系，纯粹是Next.js本身的路径解析逻辑导致的。

修复方案 #

按落地成本和维护性排序，推荐两种可用方案：

方案1：全局统一维护路径别名（最推荐，零额外依赖） #

把所有跨包会用到的路径别名全部收敛到根目录tsconfig.base.json的compilerOptions.paths里，所有子包本来就继承这个基础配置，直接就能复用这些规则；Next.js顺着web目录下tsconfig的继承链，也能读到全部别名映射，不用在多个地方重复配。
修改根目录tsconfig.base.json的paths字段，注意路径要相对于根目录填写，匹配各子包的实际位置：

{
  "compilerOptions": {
    // 其余原有配置保持不动
    "baseUrl": ".",
    "paths": {
      "@resolvers/*": ["./database/resolvers/*"],
      "@models/*": ["./database/models/*"],
      "@config/*": ["./database/config/*"]
      // 其余子包的别名都在这里统一追加即可
    }
  }
}

改完把database子包tsconfig里重复写的paths配置删掉，避免重复定义产生冲突，重启next dev就能正常识别别名加载模块。

方案2：webpack添加TS路径解析插件（适配子包独立维护别名的场景） #

如果不想把所有别名都收敛到根配置，想保留各子包独立配置自己别名的结构，就引入tsconfig-paths-webpack-plugin，让webpack主动解析引用到的外部子包的tsconfig路径规则：

1. 先在Next.js应用所在的web目录安装开发依赖：

pnpm add -D tsconfig-paths-webpack-plugin

2. 修改web/next.config.js里的webpack配置，追加插件：

const TsconfigPathsPlugin = require('tsconfig-paths-webpack-plugin');

/** @type {import('next').NextConfig} */
const nextConfig = {
    experimental: {
        externalDir: true,
    },
    reactStrictMode: true,
    webpack: (config, { isServer }) => {
        // 新增：让webpack解析外部tsconfig的paths配置
        config.resolve.plugins.push(new TsconfigPathsPlugin({}));

        // 原有配置保持不变
        config.resolve.fallback = { fs: false }
        config.experiments = {
            topLevelAwait: true,
            syncWebAssembly: true,
            asyncWebAssembly: true,
            layers: true,
        }

        if (isServer) {
            config.output.webassemblyModuleFilename = "./../static/wasm/[modulehash].wasm"
        } else {
            config.output.webassemblyModuleFilename = "static/wasm/[modulehash].wasm"
        }

        return config
    },
}

module.exports = nextConfig

如果插件默认读取的tsconfig路径不符合预期，可以给TsconfigPathsPlugin传入configFile参数，显式指定要加载的tsconfig文件路径。

注意事项 #

别图省事在web目录的tsconfig里重复抄一遍所有子包的别名，后期子包路径调整的时候要改多处，维护成本极高，优先选方案1的全局统一配置，长期稳定性最好。

内容的提问来源于stack exchange，提问作者Louis Giët