Vite+React+TS项目中tsconfig paths无法导入CSS模块问题

架构老林

2026-8-16

解决Vite-React-TS项目路径别名下CSS模块导入识别问题

1. 同步Vite配置与tsconfig路径别名

TS的tsconfig.json路径别名仅作用于TypeScript服务，Vite自身需单独配置别名才能正确解析文件，否则不仅VS Code识别异常，打包也会报错：

在vite.config.ts中添加resolve.alias配置：

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import path from 'path';

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@styles': path.resolve(__dirname, './src/styles'),
      // 其他别名同步配置在此处
    },
  },
});

2. 修正tsconfig.json的包含规则与路径配置

检查tsconfig.json的include字段，确保覆盖所有CSS模块文件，同时确认paths配置准确：

{
  "compilerOptions": {
    "baseUrl": "./src",
    "paths": {
      "@styles/*": ["styles/*"]
    },
    // 其他编译配置...
  },
  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.css", "src/**/*.module.css"],
  "exclude": ["node_modules"]
}

3. 添加CSS模块类型声明文件

TypeScript默认不识别CSS模块，需手动添加类型声明让VS Code识别：

在src目录下创建styles.d.ts（或写入已有的vite-env.d.ts），添加以下内容：

declare module '*.module.css' {
  const classes: { [key: string]: string };
  export default classes;
}

// 若使用SCSS模块，可追加以下声明
// declare module '*.module.scss' {
//   const classes: { [key: string]: string };
//   export default classes;
// }