NextJS中路径别名导入CSS Modules时VSCode类名无自动补全

问题场景 #

在NextJS项目中使用VSCode及CSS Modules扩展，已配置tsconfig和next.config.js的路径别名：

• 相对路径导入CSS文件时（import styles from "./Main.module.css"），类名自动补全正常
• 使用路径别名导入时（import commonStyles from "@styles/common.module.css"），无类名补全提示，仅显示全局自动提示
• 文件导入的自动补全功能正常，仅类名补全失效

解决方案 #

1. 配置CSS Modules扩展的路径别名映射 #

针对常用的clinyong.vscode-css-modules扩展，打开VSCode设置（Ctrl+,），搜索cssModules.importPaths，添加项目的路径别名映射：

"cssModules.importPaths": {
  "@styles": "./src/shared/UI/styles"
}

注意：这里的路径是相对于项目根目录的相对路径，而非tsconfig中的通配符格式。

2. 重启TypeScript服务 #

VSCode可能未实时加载tsconfig的路径配置，通过以下步骤刷新：

• 打开命令面板（Ctrl+Shift+P）
• 执行TypeScript: Restart TS Server命令

3. 验证扩展兼容性 #

• 确保使用的CSS Modules扩展为最新版本
• 若当前扩展仍有问题，可尝试切换至替代扩展（如mrmlnc.vscode-scss，支持CSS/SCSS Modules的补全）

4. 确认tsconfig配置有效性 #

检查tsconfig.json的paths和include配置：

• paths中的别名映射需与实际文件目录完全匹配
• include需覆盖所有需要解析的TS/TSX文件，确保路径别名能被正确识别

附：项目配置参考 #

tsconfig.json #

{
    "compilerOptions": {
        "lib": ["dom", "dom.iterable", "esnext"],
        "allowJs": true,
        "skipLibCheck": true,
        "strict": true,
        "noEmit": true,
        "esModuleInterop": true,
        "module": "esnext",
        "moduleResolution": "bundler",
        "resolveJsonModule": true,
        "isolatedModules": true,
        "jsx": "preserve",
        "incremental": true,
        "plugins": [
            {
                "name": "next"
            }
        ],
        "paths": {
            "@/*": ["./src/*"],
            "@styles/*": ["./src/shared/UI/styles/*"]
        }
    },
    "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
    "exclude": ["node_modules"]
}

next.config.js #

/** @type {import('next').NextConfig} */
const nextConfig = {
    webpack(config) {
        const fileLoaderRule = config.module.rules.find((rule) => rule.test?.test?.(".svg"));
        config.module.rules = [
            ...config.module.rules.filter((rule) => rule !== fileLoaderRule),
            { ...fileLoaderRule, exclude: /\.svg$/i },
            {
                ...fileLoaderRule,
                test: /\.svg$/i,
                resourceQuery: {
                    ...fileLoaderRule.resourceQuery,
                    not: [...fileLoaderRule.resourceQuery.not, /component/],
                },
            },
            { test: /\.svg$/i, issuer: /\.[jt]sx?$/, use: "@svgr/webpack", resourceQuery: /component/ },
        ];
        return config;
    },
};

export default nextConfig;

内容的提问来源于stack exchange，提问作者Даниил Дуров