monorepo下React无法导入本地文件系统安装npm包问题排查

算力阿峰

2026-8-28

问题背景

搭建monorepo项目，包含两个独立包：
- 使用TypeScript编写的shared包，存放服务端与客户端共用的类型、运行时数据
- 通过create-react-app --template typescript命令初始化的client包
本地依赖安装方式：在client目录执行npm i ../shared安装shared包，安装完成后client的package.json生成依赖项"shared": "file:../shared"，client的node_modules目录下存在指向shared包实际代码的软链接
项目目录结构参考：
shared包初始package.json配置如下：

"main": "dist/index.js",
"types": "dist/index.d.ts",
"scripts": {
    "build": "tsc",
    "prepare": "npm run build"
},
"files": [
    "dist/**/*"
],

问题现象

类型导入正常：client端TypeScript可以完美推导shared包的所有类型，导入类型定义无报错
运行时代码导入失败：导入shared包中的实际运行时数据时，webpack构建抛出错误
webpack报错参考：
报错时shared包编译生成的入口代码为CommonJS格式：

"use strict";
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
    if (k2 === undefined) k2 = k;
    var desc = Object.getOwnPropertyDescriptor(m, k);
    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
      desc = { enumerable: true, get: function() { return m[k]; } };
    }
    Object.defineProperty(o, k2, desc);
}) : (function(o, m, k, k2) {
    if (k2 === undefined) k2 = k;
    o[k2] = m[k];
}));
var __exportStar = (this && this.__exportStar) || function(m, exports) {
    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
};
Object.defineProperty(exports, "__esModule", { value: true });
__exportStar(require("./enums"), exports);
__exportStar(require("./interfaces"), exports);

核心诉求：实现客户端与服务端之间的TypeScript代码共享，解决构建报错问题。

报错原因

报错核心来自两个配置冲突：

create-react-app内置的webpack默认不会编译node_modules目录下的代码，软链接形式安装的本地shared包会被识别为第三方依赖，跳过babel转译流程
shared包默认编译输出CommonJS模块格式，和CRA默认的ES模块解析规则存在兼容问题，导致运行时导入失败
类型导入不受影响是因为TypeScript类型检查独立于webpack编译流程，只读取types字段指向的类型声明文件即可完成推导，不需要处理运行时代码。

解决方案

按以下步骤调整配置即可正常编译：

调整shared包TypeScript编译配置，输出ES模块
打开shared目录下的tsconfig.json，修改compilerOptions配置：

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "Node",
    "declaration": true,
    "outDir": "./dist",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "strict": true
  },
  "include": ["src/**/*"]
}

更新shared包package.json的模块入口字段
新增module字段，让webpack优先识别ES模块格式的产物：

{
  "main": "dist/index.js",
  "module": "dist/index.js",
  "types": "dist/index.d.ts",
  "scripts": {
    "build": "tsc",
    "prepare": "npm run build"
  },
  "files": [
    "dist/**/*"
  ]
}

修改CRA的webpack配置，支持编译软链接本地包
不建议直接eject CRA（操作不可逆），先在client目录执行npm i @craco/craco -D安装配置覆写工具，再在client根目录新建craco.config.js文件，写入以下配置：

const path = require('path');
module.exports = {
  webpack: {
    configure: (config) => {
      config.resolve.symlinks = true;
      const jsTsRule = config.module.rules[1].oneOf.find(rule => 
        rule.test && rule.test.toString().includes('js|ts')
      );
      if (jsTsRule) {
        jsTsRule.include = [
          jsTsRule.include,
          path.resolve(__dirname, '../shared/src')
        ];
      }
      return config;
    }
  }
}

同时修改client包package.json中的启动、构建命令，把react-scripts替换为craco：

"scripts": {
  "start": "craco start",
  "build": "craco build",
  "test": "craco test"
}

清理缓存重启服务
- 在shared目录重新执行npm run build生成最新ES模块产物
- 回到client目录删除node_modules/.cache缓存文件夹，执行npm start即可正常构建运行。

长期维护更简便的方案：可以直接使用pnpm/yarn workspace配合tsconfig路径别名，让webpack和TypeScript直接引用shared包源码，不需要提前编译shared包，后续修改shared代码也不需要重复执行build命令。

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