TypeScript+React项目路径别名本地运行无效问题求助

问题排查与修复方案 #

1. 对齐TS配置与Webpack别名映射 #

编辑器能跳转说明tsconfig.json的路径配置是有效的，但Webpack不认，核心原因是TS的paths和Webpack的resolve.alias未完全匹配。

• 先检查tsconfig.json的baseUrl和paths：
  如果源码在src目录，推荐配置：

  {
    "compilerOptions": {
      "baseUrl": "./src",
      "paths": {
        "@/*": ["*"]
      }
    }
  }
  

  对应Webpack的配置要完全匹配：

  // webpack.config.js
  const path = require('path');
  
  module.exports = {
    resolve: {
      alias: {
        '@': path.resolve(__dirname, 'src')
      },
      // 务必添加TS相关扩展名，避免Webpack找不到对应文件
      extensions: ['.ts', '.tsx', '.js', '.jsx']
    }
  }
  

  要是你用的是@/src/*这种映射，那Webpack的别名要写成：

  alias: {
    '@/src': path.resolve(__dirname, 'src')
  }
  

2. 针对Create React App（CRA）项目的特殊处理 #

如果是CRA项目，直接修改webpack配置文件无效，因为CRA会覆盖自定义配置。需要用craco或react-app-rewired来修改：

• 安装依赖：npm install @craco/craco --save-dev
• 项目根目录新建craco.config.js：

  const path = require('path');
  
  module.exports = {
    webpack: {
      alias: {
        '@': path.resolve(__dirname, 'src')
      }
    },
    typescript: {
      enableTypeChecking: true
    }
  }
  

• 修改package.json的启动脚本，替换react-scripts为craco：

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

3. 清除缓存并重启服务 #

缓存会导致配置不生效，执行以下操作：

• 停止本地开发服务
• 删除node_modules/.cache目录（CRA项目）或Webpack缓存目录
• 重启服务，必要时重新执行npm install

4. 检查路径大小写与拼写 #

编辑器可能不区分大小写，但Webpack在Linux/macOS环境下会严格区分，确保引用路径和实际文件路径的大小写、拼写完全一致。

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