必须加 declare module 声明，否则 import styles from './button.module.css' 直接报 ts2307 错误；只加声明还不够，需配置 typescript-plugin-css-modules 插件并重启 ts 服务，才能实现类名补全与跳转。
必须加 declare module 声明，否则 import styles from './Button.module.css' 直接报 TS2307 错误；只加声明还不够，要配插件才能有类名补全。
为什么 import styles from './xxx.module.css' 会报错？
TypeScript 默认根本不认识 .module.css 这种后缀，它不是 JS/TS 文件，也不是已知的模块类型。报错信息通常是：Cannot find module './Button.module.css' or its corresponding type declarations——这不是构建失败，是类型检查阶段就卡住了。
- 错误和 Webpack/Vite 配置无关：即使样式已正确注入页面，TS 编译器仍拒绝这个
import - 大小写敏感：文件是
button.module.css，但import写成Button.module.css，Linux/macOS 下必报错 -
tsconfig.json的include没覆盖到声明文件，也会导致声明不生效
最简类型声明怎么写？
在项目里新建一个 src/globals.d.ts（必须是 .d.ts 后缀），内容只写这一行：
PigX UI 前端开发
下载
PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。
declare module '*.module.css' { const classes: { [key: string]: string }; export default classes; }
- 别写成
declare module '*.css'：它会干扰import 'bootstrap.css'这类全局引入 - 如果还用
.module.scss或.module.less，每种都得单独加一行declare module - 不要加
export =、const以外的修饰符，也不要给classes赋初始值
如何让 styles.primary 有自动补全和拼写校验？
仅靠上面的声明，TS 知道 styles 是个对象，但不知道它有哪些 key。要获得 IDE 补全，必须启用 typescript-plugin-css-modules 插件：
- 安装：
pnpm add -D typescript-plugin-css-modules（或 npm/yarn） - 在
tsconfig.json的compilerOptions里加："plugins": [{ "name": "typescript-plugin-css-modules" }] - 重启 TS Server：VS Code 中按
Ctrl+Shift+P→ 输入 “TypeScript: Restart TS server” - 插件默认只识别
.module.css、.module.scss等带.module.的文件名；若用.css但启用了 modules，需在插件options中配customMatcher
常见失效场景和排查点
声明写了、插件装了、配置也加了，但补全还是没反应——大概率是这几个地方卡住了：
- VS Code 使用的是工作区内的 TypeScript 版本，不是全局的；确认右下角显示的 TS 版本与项目
node_modules/typescript一致 - 声明文件路径没被
tsconfig.json的include匹配到，比如写成了"include": ["src/**/*"]却把globals.d.ts放在了项目根目录 - 插件未生效：打开 VS Code 的 TypeScript 输出面板（Output → TypeScript），搜索 “css-modules”，看有没有加载日志
- 类名含连字符（如
icon-left）时，补全可能不触发，这是插件当前限制，建议改用camelCase类名或手动在声明中加引号字段
类型声明和插件是两层事：声明解决编译错误，插件解决开发体验。漏掉任何一层，都会在实际编码中立刻暴露出来。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
