必须手动添加 CSS Modules 类型声明文件，因为 Vue SFC 对 .module.css 的导入是运行时行为，TypeScript 默认无法识别，导致 styles.xxx 报错且无类型提示。
CSS Modules 在 Vue3 + TypeScript 项目中默认不提供类型提示，必须手动补全声明文件，否则 styles.xxx 会报 Property 'xxx' does not exist on type '{} 错误。
为什么 import styles from './Button.module.css' 没有类型提示
Vue 的 SFC（单文件组件）对 .module.css 文件的导入是运行时行为，TypeScript 默认不认识这种模块格式。即使你用了 lang="ts"，TS 编译器仍会把 styles 当作空对象 {}，因为缺少对应的类型声明。
常见错误现象：
-
Cannot find name 'styles'（未声明模块） -
Property 'primary' does not exist on type '{ }'（有导入但无类型） - VS Code 中
styles.后无自动补全
补全 *.module.css 类型声明（关键一步）
在项目 src 目录下新建 shims-css-modules.d.ts（或合并进已有 shims-vue.d.ts），内容如下：
立即学习“前端免费学习笔记（深入）”；
vue-component-analyzer
下载
递归分析 Vue 项目组件依赖，从入口文件生成组件层级图，支持 Vue 2/3，输出组件名、文件路径和属性。适用于分析组件结构、排查依赖或了解项目架构。
declare module '*.module.css' {
const classes: Record<string, string>;
export default classes;
}
declare module '*.module.scss' {
const classes: Record<string, string>;
export default classes;
}
declare module '*.module.sass' {
const classes: Record<string, string>;
export default classes;
}
说明：
- 必须用
declare module '*.module.css'，不能写成declare module '.*.css'或漏掉.module -
Record<string, string>是最简兼容写法；若需更精确（如只允许预定义类名），可改用{ primary: string; secondary: string }，但需和实际 CSS 类名完全一致 - 如果同时用 SCSS/SASS，也要一并声明，否则对应后缀文件同样无提示
在 <script setup lang="ts"> 中正确使用
确保组件启用 lang="ts"，且导入路径带 .module.css 后缀：
<script setup lang="ts">
import styles from './Button.module.css'
const props = defineProps<{ type?: 'primary' | 'secondary' }>()
</script>
<template>
<button :class="styles[props.type || 'primary']">Click</button>
</template>
注意点：
- 不要写
import './Button.module.css'（无默认导出，无法解构） - 不要省略后缀写成
import styles from './Button'（Vite/Webpack 不会触发 CSS Modules 处理） - 若用
defineComponent()写法，同样适用该声明文件，无需额外配置 - Vite 用户无需改
vite.config.ts，CSS Modules 默认开启；Webpack 用户需确认css-loader的modules: true
调试时类名乱码？调整 localIdentName 即可
开发期类名如 Button__primary--abc12 难以识别，可在构建配置中简化：
- Vite：在
vite.config.ts的css.modules选项里设localsConvention: 'camelCase'，并自定义generateScopedName - Webpack：在
css-loader的options.modules.localIdentName改为[name]__[local]
这不影响类型提示，只影响生成的 CSS 类名可读性。真正容易被忽略的是：类型声明文件必须放在 include 路径内（tsconfig.json 的 "include": ["src/**/*.ts", "src/**/*.d.ts", ...]），否则 TS 根本不会加载它。
