全局 declare module '*.module.css' 仅让 TypeScript 编译通过，但无法提供类名提示、拼写检查和安全重构；需用 css-module-types 或 vite-plugin-css-modules-typings 为每个 .module.css 生成精确的 .d.ts 类型声明文件。

为什么全局 declare module '*.module.css' 不够用

它能让 TypeScript 编译通过，但 styles.xxx 中的 xxx 是任意字符串——IDE 不提示、拼错类名不报错、重构时无法安全重命名。真正需要的是把每个 .module.css 文件里实际定义的类名，变成具体可校验的 export const xxx: string。

用 css-module-types 生成精确的 .d.ts 文件

这是目前最轻量、零配置、兼容 Webpack/Vite 的方案：

• 运行 npx css-module-types src/**/*.module.css，会在每个 CSS 文件同目录下生成 Button.module.css.d.ts 这样的文件
• 生成内容类似：

  export const primary: string;
  export const disabled: string;

• 必须确保 tsconfig.json 的 include 包含这些 .d.ts 文件路径，例如："include": ["src/**/*", "src/**/*.d.ts"]
• 不要手动修改生成的 .d.ts，它们会被覆盖；也不要把它们加进 Git（除非你明确需要版本锁定）

Vite 用户注意 vite-plugin-css-modules-typings

如果你用 Vite 且希望在开发时自动更新类型定义（比如保存 CSS 就刷新 .d.ts），css-module-types 的 CLI 模式不够实时。此时应换用：

Scrapfly SDK TypeScript

使用 Scrapfly SDK（scrapfly-sdk）在 TypeScript 或 JavaScript 中进行网页抓取，用于用户请求抓取 URL、绕过反爬虫防护、渲染页面等场景。

下载

• 安装：pnpm add -D vite-plugin-css-modules-typings
• 在 vite.config.ts 中添加插件：

  import cssModulesTypings from 'vite-plugin-css-modules-typings';
  export default defineConfig({
    plugins: [cssModulesTypings()]
  });

• 它会监听 .module.css 变更，并自动生成/更新对应 .d.ts，无需手动运行命令
• 注意：该插件默认不处理 .module.scss，需显式配置 extensions: ['.module.css', '.module.scss']

别忽略 IDE 缓存和重启时机

即使 .d.ts 已生成，VS Code 有时仍显示“Property 'xxx' does not exist”，常见原因有：

• TS Server 没感知到新文件：按 Ctrl+Shift+P → 输入 “Restart TS server” 手动重启
• 文件路径不匹配：生成的 Button.module.css.d.ts 必须和 Button.module.css 在同一目录，不能放在 types/ 下
• 用了 typescript-plugin-css-modules 插件但没关掉它对类型定义的“覆盖行为”：该插件默认会接管类型推断，若同时存在手动生成的 .d.ts，建议禁用它的 generateTypes 选项

类名映射不是魔法，是构建阶段和语言服务协同的结果——缺一环，类型就断了。

前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！