Turborepo+Next.js使用imports路径别名构建报错：无法解析#模块

问题 #

用Turborepo搭建了monorepo，包编译环节正常，但构建包含Next.js应用的整个monorepo时出现错误。

Web应用配置 #

package.json

{
  "name": "@piszczj/web",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev --turbopack",
    "dev:debug": "cross-env NODE_OPTIONS='--inspect' next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "postbuild": "next-sitemap --config next-sitemap.config.js",
    "oslllo-svg-fixer": "node node_modules/oslllo-svg-fixer/src/cli.js"
  },
  "imports": {
    "#src/*": [
      "./src/*.ts",
      "./src/*.tsx"
    ],
    "#src/types": "./src/types/index.ts",
    "#src/components/draggable-tree": "./src/components/draggable-tree/index.ts"
  },
  "dependencies": {
    "@piszczj/rich-text-editor": "*",
    "@piszczj/typescript-config": "*",
    "@piszczj/form": "*",
    "@piszczj/utils": "*",
    "@piszczj/react-utils": "*",
    "@piszczj/video-player": "*",
    "@piszczj/files": "*",
     ...
  
  },
  "devDependencies": {
    "@piszczj/types": "*",
    ...
 
  },
  "engines": {
    "node": ">=18.0.0 <22.0.0"
  }
}

tsconfig.json

{
  "extends": "@piszczj/typescript-config/nextjs.json",
  "compilerOptions": {
    "plugins": [
      {
        "name": "next"
      }
    ]
  },
  "include": [
    "**/*.ts",
    "**/*.tsx",
    "next-env.d.ts",
    "next.config.js",
    ".next/types/**/*.ts"
  ],
  "exclude": ["node_modules"]
}

导入代码 #

在./src/api/exam-formula/hooks.ts中的导入：

import {
  getCanReviewLecture,
  getLecture,
  getLectures,
  getMyLectures,
  getMyLecturesSubjects,
  getSelectableLectureSorting,
  getSelectableSchoolLevels,
  removeLecture,
  saveLecture,
  updateLecture,
  toggleLectureEnabled,
} from '#src/api/lecture/lecture.service';

import { queryClient } from '#src/lib/global-providers';

错误信息 #

VS Code和TypeScript无报错，但执行npm run build时出现：

@piszczj/web:build: ./src/api/exam-formula/hooks.ts
@piszczj/web:build: Module not found: Can't resolve '#src/lib/global-providers'
...

@piszczj/web:build: > Build failed because of webpack errors
@piszczj/web:build: npm error Lifecycle script `build` failed with error:
@piszczj/web:build: npm error code 1
@piszczj/web:build: npm error path D:\git\math-wizards-app\apps\web
@piszczj/web:build: npm error workspace @piszczj/web@0.1.0
@piszczj/web:build: npm error location D:\git\math-wizards-app\apps\web
@piszczj/web:build: npm error command failed
@piszczj/web:build: npm error command C:\WINDOWS\system32\cmd.exe /d /s /c next build
@piszczj/web:build: ERROR: command finished with error: command (D:\git\math-wizards-app\apps\web) C:\Program Files\nodejs\npm.cmd run build exited (1)
@piszczj/web#build: command (D:\git\math-wizards-app\apps\web) C:\Program Files\nodejs\npm.cmd run build exited (1)

原因与解决方案 #

1. 核心原因 #

你在package.json的imports字段配置了路径别名，但Next.js的构建依赖Webpack，而package.json的imports目前不被Next.js/Webpack完全支持——只有TypeScript能识别这个别名，导致Webpack打包时无法解析模块路径，最终报错。

2. 修复步骤 #

需要同时在TypeScript和Next.js配置中适配路径别名，确保两者都能正确解析：

步骤1：在tsconfig.json中添加paths配置

修改compilerOptions，添加paths字段，让TypeScript识别别名：

{
  "extends": "@piszczj/typescript-config/nextjs.json",
  "compilerOptions": {
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "#src/*": ["./src/*"],
      "#src/types": ["./src/types/index.ts"],
      "#src/components/draggable-tree": ["./src/components/draggable-tree/index.ts"]
    }
  },
  "include": [
    "**/*.ts",
    "**/*.tsx",
    "next-env.d.ts",
    "next.config.js",
    ".next/types/**/*.ts"
  ],
  "exclude": ["node_modules"]
}

步骤2：在next.config.js中配置Webpack别名

Next.js需要通过配置告诉Webpack如何解析别名，添加以下内容：

/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config) => {
    config.resolve.alias = {
      ...config.resolve.alias,
      '#src': './src',
      '#src/types': './src/types/index.ts',
      '#src/components/draggable-tree': './src/components/draggable-tree/index.ts',
    };
    return config;
  },
};

module.exports = nextConfig;

步骤3：移除package.json中的imports字段

既然已经通过TypeScript和Webpack配置了别名，package.json里的imports字段可以直接删除，避免潜在冲突。

3. 额外检查 #

• 确认./src/lib/global-providers.ts（或.tsx）文件确实存在，路径拼写完全正确（注意大小写，Webpack打包时会严格区分）。
• 如果你的@piszczj/typescript-config/nextjs.json已经包含paths配置，确保它和项目级tsconfig.json的配置没有冲突。

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