React项目路径别名失效：模块找不到与TS类型声明错误求助

将项目中所有.css文件改为.module.css后，启动React应用出现两类错误：

1. Webpack编译错误：Module not found: Error: Can't resolve '@styles/footer.module.css' in 'N:\project name\web2\src\components'
2. TypeScript类型错误：TS2307: Cannot find module '@components/dashboard' or its corresponding type declarations

使用react-app-alias和react-app-rewired实现路径别名，目标是用import "@styles/footer.module.css"替代相对路径导入。

现有配置文件 #

tsconfig.json #

{
  "extends": "./tsconfig.paths.json",
  "compilerOptions": {
    "target": "es5",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noFallthroughCasesInSwitch": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx"
  },
  "include": ["src"]
}

tsconfig.paths.json #

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

config-overrides.js #

const { aliasWebpack, aliasJest, configPaths } = require("react-app-alias");

const options = {
  alias: configPaths("./tsconfig.paths.json"),
  tsconfig: "./tsconfig.paths.json",
  baseUrl: "./src",
};

module.exports = aliasWebpack(options);
module.exports.jest = aliasJest(options);

项目结构 #

web2
-- node_modules
-- public
-- src
  -- assets
  -- components
    -- components (like home, login)
  -- context
  -- interfaces
  -- styles
    -- component styles
  -- App.tsx
  -- index.tsx
  -- router.tsx
  -- typing.d.ts
-- .gitignore
-- config-overrides.js
-- package-lock.json 
-- package.json
-- README.md
-- tsconfig.json
-- tsconfig.paths.json

解决步骤 #

1. 修复config-overrides.js冗余配置 #

原配置中重复指定的tsconfig和baseUrl可能导致路径解析冲突，简化为：

const { aliasWebpack, aliasJest, configPaths } = require("react-app-alias");

const aliasConfig = configPaths("./tsconfig.paths.json");
module.exports = aliasWebpack({ alias: aliasConfig });
module.exports.jest = aliasJest({ alias: aliasConfig });

2. 验证依赖版本兼容性 #

确保react-app-alias适配当前Create React App（CRA）版本，若使用CRA 5.x，更新到最新版：

npm install react-app-alias@latest --save-dev

3. 清理Webpack缓存 #

删除缓存目录避免旧解析规则残留：

# Linux/Mac
rm -rf node_modules/.cache

# Windows
rd /s /q node_modules\.cache

4. 解决TypeScript类型报错 #

• 重启VSCode的TypeScript语言服务：按下Ctrl+Shift+P，选择TypeScript: Restart TS Server
• 确认src/components/dashboard目录下存在可导入文件（如index.tsx或dashboard.tsx），若无索引文件，需修改导入路径为@components/dashboard/dashboard.tsx

5. 检查文件命名与路径 #

• 确认src/styles/footer.module.css文件存在，文件名大小写与导入语句完全一致（Webpack/TS会严格校验）
• 核对tsconfig.paths.json中的paths映射无拼写错误，baseUrl确实指向./src

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