React TypeScript项目中短路径导入失效问题排查

问题根源 #

Create React App（CRA）默认的Webpack配置不会自动识别tsconfig.json里的paths别名规则——TypeScript编译器能识别这个别名做语法校验，但Webpack打包时无法解析该路径，所以会抛出模块找不到的错误。

可行解决方法 #

方法一：用craco重写配置（推荐） #

1. 安装依赖

npm install @craco/craco @types/node --save-dev

2. 在项目根目录新建craco.config.js，添加别名映射

const path = require('path');

module.exports = {
  webpack: {
    alias: {
      '@': path.resolve(__dirname, 'src/'),
      '@components': path.resolve(__dirname, 'src/components/')
      // 可根据需求扩展更多别名
    }
  },
  typescript: {
    enableTypeChecking: true
  }
};

3. 修改package.json里的启动脚本，替换为craco命令

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

4. 保持tsconfig.json的配置正确

{
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": {
      "@/*": ["./*"],
      "@components/*": ["./components/*"]
    }
    // 保留其他原有配置
  }
}

方法二：利用baseUrl特性（无需额外依赖） #

既然已经把baseUrl设为./src，可以直接省略别名前缀，用相对根目录的路径导入：

import PasswordTip from 'components/PasswordTip/PasswordTip';

Webpack会自动从src目录开始查找模块，虽然没有别名直观，但无需修改Webpack配置。

注意事项 #

• 修改配置后必须重启开发服务器，新配置才会生效
• 如果用VS Code，建议重启编辑器让TypeScript语言服务重新识别别名规则

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