TypeScript+React项目非相对路径导入layouts模块启动报错排查

问题本质 #

编辑器中按Ctrl+左键可正常跳转，说明TS语言服务已经识别了路径映射规则，但项目构建工具未同步配置别名解析规则，导致启动时无法找到非相对路径导入的layouts依赖。

修复步骤 #

1. 确认TS配置正确 #

在项目根目录的tsconfig.json中，确保compilerOptions下的基础路径和路径映射配置匹配你的目录结构：

{
  "compilerOptions": {
    "baseUrl": "src",
    "paths": {
      "layouts": ["components/layouts"],
      "layouts/*": ["components/layouts/*"]
    }
  }
}

这部分配置仅对TS/编辑器的类型提示、跳转生效，Create React App默认的构建流程不会读取该规则做模块打包。

2. 配置构建工具识别别名 #

Create React App原生不支持自定义短路径别名，可根据需求选以下任意一种方案：

零配置方案（无额外依赖）

保留baseUrl: "src"配置，直接使用基于src目录的绝对路径导入，不需要额外修改构建配置，CRA原生支持该写法：

import { MainLayout } from "components/layouts";

自定义短别名方案（无需eject）

如果必须使用import { MainLayout } from "layouts"的写法，通过craco扩展webpack配置即可：

• 安装依赖：

npm install @craco/craco

• 在项目根目录新建craco.config.js文件，添加别名配置：

const path = require('path');
module.exports = {
  webpack: {
    alias: {
      'layouts': path.resolve(__dirname, 'src/components/layouts')
    }
  }
};

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

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

配置完成后重新执行npm start，即可正常识别别名导入。

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