TypeScript本身不处理CSS，引入CSS Modules必须添加类型声明文件（如declare module '*.module.css'），否则报TS2307错误；还需启用typescript-plugin-css-modules插件并重启TS服务，才能实现类名补全与跳转。
TypeScript 本身不处理 CSS，引入 CSS 的关键在于构建工具（如 Vite、Webpack）能否把 CSS 解析并注入到页面，以及 TypeScript 能否“理解”你 import 的 CSS 模块类型。直接写 import './styles.css' 在大多数现代配置下能跑通，但若用 CSS Modules（如 Button.module.css），TS 必报 TS2307 —— 不是代码错，是缺类型户口本。
普通 CSS 文件：import './xxx.css' 能直接用，但得确认构建工具配对了
这是最轻量的引入方式，适用于全局样式或 reset 类文件：
-
import './styles.css'在.ts或.tsx中写就行，不返回值，只触发样式加载 - 必须确保构建工具已配置对应 loader：Vite 默认支持；Webpack 需装
style-loader+css-loader，且module.rules匹配/\.css$/ - 如果 import 后样式没生效，先检查浏览器开发者工具的
Network标签页里是否加载了该 CSS 文件，再查控制台有无Failed to load resource - 不要在
.ts里用document.createElement('link')动态插入 —— 构建工具无法静态分析，热更新和 HMR 会失效
CSS Modules：import styles from './xxx.module.css' 必须补类型声明
否则 TS 编译直接失败，报错 Cannot find module './Button.module.css' or its corresponding type declarations：
- 最简方案：在
src/globals.d.ts（后缀必须是.d.ts）里加一行：declare module '*.module.css'; - 确保
tsconfig.json的include包含该文件，例如："include": ["src/**/*", "src/globals.d.ts"] - 这个声明能让编译通过，但
styles.xxx没智能提示 —— 因为 TS 只知道它是个{ [key: string]: string }，不知道具体有哪些类名 - 路径大小写必须完全一致：
button.module.css≠Button.module.css；Windows 下可能不敏感，Linux/macOS 会直接报错
想获得类名自动补全？得让 TS 知道每个 .module.css 具体导出什么
手动写 .d.ts 文件太重，推荐用插件自动推导：
立即学习“前端免费学习笔记（深入）”；
- 安装
typescript-plugin-css-modules（Vite / Webpack 均支持），并在tsconfig.json的plugins数组中启用 - 插件会实时扫描
.module.css内容，生成精准类型，styles.primary有补全、拼写校验、F12 跳转 - 连字符类名（如
icon-left）会被自动转成驼峰（iconLeft），前提是构建工具开启exportLocalsConvention: 'camelCaseOnly'（Webpack css-loader）或 Vite 默认行为 - 别信“重启 VS Code 就好”——改了声明文件后，务必手动触发
Restart TS Server（Ctrl+Shift+P → “TypeScript: Restart TS server”）
动态 import CSS：仅限现代环境，且不能用于 CSS Modules
await import('./styles.css') 是合法语法，但实际意义有限：
- 它触发的是构建工具的代码分割逻辑，生成独立 CSS chunk 并插入
<head>，适合按需加载主题或大模块样式 - 返回值是空对象（
{}），不是样式类名映射，所以不适用于.module.css - Vite 支持，Webpack 5+ 支持，但旧版 Webpack 或未启用
magic comments时可能 fallback 到 JS chunk - 注意：动态 import 的 CSS 无法被 TS 类型系统捕获，
import()返回类型只能是Promise<any>，无类型安全可言
真正容易被忽略的点是：CSS Modules 的类型声明文件必须放在 TS 能扫描到的路径下，且不能命名为 .ts；而构建工具输出的类名格式（比如带路径哈希还是纯哈希）必须和 TS 插件/声明里的预期一致，否则补全会漏掉某些类名。
