NX 17 React项目迁移后无法解析内部库导入问题求助

问题背景 #

从NX15迁移到NX17后，项目内3个React应用与5个库之间，根路径导入（如import { useResetPasswordStore } from '@istekhara/store'）正常，但导入库的子目录（如@istekhara/ui/components）时，出现「导入的依赖无法解析」错误，tsconfig.base.json中已配置通配符路径但未生效。

核心原因 #

NX17默认采用Vite作为构建工具，相比NX15常用的Webpack，模块解析规则存在差异：

1. 库需要明确配置package.json的exports字段，声明子目录的导出规则
2. 应用的tsconfig需同步配置子目录的路径映射
3. Vite的路径别名需与tsconfig对应（或通过NX插件自动同步）

修复步骤 #

1. 为库配置package.json的exports字段 #

在每个库的package.json（如libs/ui/package.json）中添加exports，指定所有需要对外暴露的子路径：

{
  "name": "@istekhara/ui",
  "version": "0.0.1",
  "exports": {
    ".": "./src/index.ts",
    "./components": "./src/components/index.ts",
    "./layout": "./src/layout/index.ts",
    "./forgot-password-page": "./src/forgot-password-page/index.ts",
    "./reset-password-page": "./src/reset-password-page/index.ts",
    "./not-found-page": "./src/not-found-page/index.ts",
    "./icons": "./src/icons/index.ts",
    "./wrapper": "./src/wrapper/index.ts",
    "./styled": "./src/styled/index.ts",
    // 通配符覆盖所有子目录（可选，需确保每个子目录有index.ts）
    "*": "./src/*"
  }
}

注意：每个子目录下必须存在index.ts，导出该目录内的模块，否则无法被正确解析。

2. 更新应用的tsconfig.app.json路径映射 #

在应用的tsconfig.app.json中，补充子目录的通配符路径配置：

"paths": {
  "@alim/*": ["src/*"],
  "@istekhara/common": ["../../libs/common/src/index.ts"],
  "@istekhara/common/*": ["../../libs/common/src/*"],
  "@istekhara/hooks": ["../../libs/hooks/src/index.ts"],
  "@istekhara/hooks/*": ["../../libs/hooks/src/*"],
  "@istekhara/service": ["../../libs/service/src/index.ts"],
  "@istekhara/service/*": ["../../libs/service/src/*"],
  "@istekhara/store": ["../../libs/store/src/index.ts"],
  "@istekhara/store/*": ["../../libs/store/src/*"],
  "@istekhara/theme": ["../../libs/theme/src/index.ts"],
  "@istekhara/theme/*": ["../../libs/theme/src/*"],
  "@istekhara/ui": ["../../libs/ui/src/index.ts"],
  "@istekhara/ui/*": ["../../libs/ui/src/*"]
}

3. 确保Vite配置同步路径映射 #

如果使用Vite构建，检查项目的vite.config.ts是否启用了nxViteTsPaths插件（该插件会自动读取tsconfig的路径配置）：

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';

export default defineConfig({
  plugins: [react(), nxViteTsPaths()],
});

若插件未自动生效，可手动添加别名配置：

resolve: {
  alias: {
    '@istekhara/ui': '../../libs/ui/src/index.ts',
    '@istekhara/ui/*': '../../libs/ui/src/*',
    // 其他库的别名配置
  },
}

4. 清理缓存并重启服务 #

执行命令清理NX缓存，避免旧配置残留：

npx nx reset

然后重新启动开发服务器：

npx nx serve admin

内容的提问来源于stack exchange，提问作者Syed Kounain Abbas Rizvi