VSCode 如何使用 CSS Modules 智能提示

不少开发者都遇到过这样的困扰：明明按照规范写了CSS Modules，但在VSCode里敲styles.时，期待的类名提示却迟迟不出现。这背后的原因，其实并非插件安装不全，而是一个更根本的类型信息缺失问题。

VSCode 默认不识别 CSS Modules 的模块导出结构，styles 被视为普通对象，无法推断类名；根本原因是类型信息缺失，需通过声明模块或插件生成类型定义来解决。

为什么 import styles from './Button.module.css' 没有类名提示？

简单来说，VSCode默认并不知道.module.css文件会导出一个包含具体类名的对象。它把styles当成一个普通的Ja vaScript对象，自然无法推断出它的键（也就是你的CSS类名）具体是什么。

要解决这个问题，核心思路只有两条：要么让TypeScript提前知道CSS文件会导出什么，要么借助插件让VSCode实时解析CSS文件并提供补全。

• 首选方案：使用declare module '*.module.css'类型声明，并配合css-modules-typescript-loader或@types/css-modules。这条路子能提供最稳定的类型安全和代码提示。
• 无TypeScript项目：可以安装CSS Modules Extensions插件（作者clinyong）。它会在你保存文件时，扫描.module.css文件并生成临时的类型定义文件。不过，记得确保项目根目录有tsconfig.json或jsconfig.json。
• 一个关键设置：VSCode内置的CSS语言服务对.module.css后缀的处理可能默认关闭。必要时，在settings.json中检查或设置"css.validate": false（避免无关报错）和"css.modules": true（新版VSCode通常已自动识别）。

composes 和 :global 类名为什么不提示？

这个问题有点特殊。composes和:global是CSS Modules在运行时处理的特性，VSCode的静态分析工具很难追踪这种跨文件的依赖关系或全局作用域的变化——更重要的是，这些类名根本不会作为键出现在最终的styles对象里。

这意味着，即使styles.base通过composes组合了reset样式，你在输入styles.时也看不到reset这个选项。同样，用:global(.btn)定义的样式，也不会被当作styles.btn来补全。

立即学习“前端免费学习笔记（深入）”；

• 应对composes：考虑将被复用的类单独抽离到一个.module.css文件中，并通过命名空间的方式导入（例如import base from './base.module.css'），并确保其类型声明已覆盖。
• 规避:global：尽量减少使用。对于需要全局作用的样式，可以优先考虑使用data-*属性，或者转向styled-components、Emotion这类本身就支持运行时样式的方案。
• 重要提醒：目前没有成熟的插件能完美“猜测”composes的依赖链，强行实现全量扫描会对大型项目的性能造成明显拖累。

React + Vite 项目里 CSS Modules 提示失效怎么办？

在Vite项目中遇到提示失灵，先别急着重装插件。Vite默认不会为CSS Modules生成类型声明，而且其极速的启动模式可能不触发完整的类型检查，导致TS Server“看”不到最新的模块定义。

解决问题的关键，在于让Vite和TypeScript协同工作，把类型信息暴露出来：

• 在vite.config.ts中，可以配置css.modules.generateScopedName。这虽然不是必须的，但统一的命名规则有助于后续调试。
• 核心步骤：在项目src目录下创建（或修改）env.d.ts文件，并写入以下声明：

  declare module '*.module.css' {
    const classes: Record;
    export default classes;
  }

  这种方式比全局安装@types/css-modules更轻量，也更容易控制。
• 重启TS Server：修改声明文件后，务必通过Ctrl+Shift+P打开命令面板，执行“TypeScript: Restart TS server”，否则更改可能不生效。
• 检查包含范围：确认tsconfig.json中的include字段包含了src/**/*，确保env.d.ts文件能被正确加载。

智能提示偶尔卡住或类名消失？检查这三处

如果提示时有时无，先别怀疑是VSCode出了问题。这通常是CSS模块解析链在某个环节中断了，最常见的原因集中在路径、缓存和配置上。

• 路径一致性：Button.module.css文件名和import语句中的路径必须完全一致，包括大小写。Windows系统因为默认忽略大小写，容易埋下隐患；而在Linux或macOS下，大小写不一致会直接导致导入失败。
• 清理构建缓存：尝试删除node_modules/.vite、node_modules/.cache（Vite项目）或.next（Next.js项目）目录。旧的缓存可能固化了错误的模块映射关系。
• 调整VSCode设置：在设置中，将"typescript.preferences.includePackageJsonAutoImports"的值从"auto"改为其他选项（如"off"）。这个选项有时会干扰CSS模块的解析优先级。

还有一个比较隐蔽的坑：如果CSS文件的第一行是注释或空行，某些旧版本的解析插件可能会跳过对该文件的处理。把.module.css文件的第一行直接写成CSS选择器，可以立刻验证这个问题。