React TS项目tsconfig配置路径别名启动时报模块找不到错误

核心原因 #

tsconfig.json中的paths路径别名配置仅作用于TypeScript类型校验、IDE路径识别跳转，webpack默认不会读取该配置，因此会出现IDE无报错但打包编译时找不到模块的问题。 #

分场景解决方案 #

场景1：基于create-react-app创建、未执行npm run eject的项目 #

• 安装所需依赖：

npm install @craco/craco craco-alias -D

• 在项目根目录新建craco.config.js配置文件，写入以下内容，直接复用tsconfig中的别名配置，避免两边重复维护：

const CracoAlias = require("craco-alias");

module.exports = {
  plugins: [
    {
      plugin: CracoAlias,
      options: {
        source: "tsconfig",
        tsConfigPath: "./tsconfig.json",
      },
    },
  ],
};

• 修改package.json中的scripts命令，将原有的react-scripts替换为craco：

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

• 终止原有的dev服务进程，重新执行npm run start即可正常编译。

场景2：已eject的CRA项目/手动搭建webpack配置的项目 #

• 找到项目中的webpack配置文件（通常路径为config/webpack.config.js），在resolve.alias字段中添加和tsconfig对应的路径映射：

const path = require('path');

module.exports = {
  // 其余webpack配置保持不变
  resolve: {
    // 其余resolve配置保持不变
    alias: {
      // 其余已有别名配置保持不变
      '@utils': path.resolve(__dirname, 'src/utils'),
      // 若配置了@components、@assets等其他别名，在此处同步添加即可
    },
    // 确认已配置后缀自动解析，否则导入时需要写全文件后缀
    extensions: ['.tsx', '.ts', '.jsx', '.js', '.json']
  }
}

• 保存配置后重启dev服务即可生效。

排查校验步骤 #

如果配置后仍报错，按以下顺序逐一核对：

• 检查tsconfig.json配置格式是否正确，compilerOptions下必须先配置baseUrl，paths路径要和baseUrl对应：

  {
    "compilerOptions": {
      // 如果baseUrl设为"./src"，paths中无需加src前缀
      "baseUrl": "./src",
      "paths": {
        "@utils/*": ["utils/*"]
      }
    }
  }
  

  如果baseUrl设为项目根目录"./"，则paths要写成"@utils/*": ["src/utils/*"]，webpack侧的alias路径也要同步对齐

• 确认webpack侧的别名映射路径和tsconfig中的路径完全一致，不要出现一侧指向src/utils、另一侧指向根目录utils的错位问题
• 所有配置修改完成后，必须终止原有dev服务进程重新启动，webpack配置改动不会触发热更新，不重启不会加载新配置

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