TypeScript 默认不识别 .css 或 .scss 文件导入，需通过 .d.ts 声明文件告知其存在及导出结构；应声明 *.module.css 和 *.module.scss 模块，避免全局 *.css 声明导致副作用导入报错；声明文件须被 tsconfig.json 的 include 覆盖才能生效。

TypeScript 默认不识别 .css 或 .scss 文件的导入，直接写 import './style.css' 会报错“找不到模块”。这不是 Webpack 或 Vite 配置问题，而是 TS 编译器层面的类型缺失——必须通过 .d.ts 声明文件告诉它：“这类文件存在，且导出一个对象”。

为什么 import './xxx.module.css' 会报 TS 错误

TS 只认 JS/TS 模块的导出结构，而 CSS 文件在运行时由 loader（如 css-loader）处理成对象，但编译期 TS 完全不知道这个对象长什么样。没有声明，styles.button 就是 any，甚至根本无法 import 成功。

• 错误现象：Cannot find module './Button.module.css' 或 Module has no exported member 'xxx'
• 本质原因：TS 类型系统未被告知该模块的存在和形状
• 不是“loader 没生效”，而是“TS 编译阶段就卡住了”，即使 CSS 最终能正确注入页面，TS 也会报错并可能中断 IDE 智能提示

如何写一个有效的 CSS Modules 声明文件

声明文件必须放在 TS 能扫描到的路径下（如项目根目录或 src/types），且文件名以 .d.ts 结尾。内容不能有实现，只描述类型。

• 对所有 *.module.css 文件统一声明：

  declare module '*.module.css' {
    const classes: { [key: string]: string };
    export default classes;
  }

• 如果还用 SCSS Modules，补上这一行：

  declare module '*.module.scss' {
    const classes: { [key: string]: string };
    export default classes;
  }

• 文件名建议为 types/css-modules.d.ts 或 src/custom.d.ts，确保被 tsconfig.json 的 include 或 typeRoots 覆盖
• 不要写 export = 或 export default 以外的导出；不要给 classes 赋值；不要加 const 以外的修饰符

为什么不能只声明 *.css 而要限定 *.module.css

全局 *.css 声明会影响非模块化 CSS 导入（比如 import 'bootstrap/dist/css/bootstrap.min.css'），这类导入通常无默认导出，只做副作用引入。若声明了 export default，TS 会强制要求你接收返回值，导致编译失败。

Galileo TypeScript sdk

完整的Galileo AI平台 TypeScript/JS SDK 参考，用于评估、观察和保护 GenAI 应用。适用于构建 Node.js 或 TypeScript 项目。

下载

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

• 安全做法：只声明明确启用模块化的后缀，如 *.module.css、*.module.scss
• Webpack/Vite 中，模块化 CSS 通常靠文件名约定（.module.css）或规则 modules: true 触发，TS 声明应与之对齐
• 如果你用的是 css-loader 的 modules: { auto: true }，那可以考虑声明 *.css，但需确认项目中所有 .css 确实都走模块化流程

声明后仍提示类名不存在？检查类型精度

上面的基础声明把所有类名都当作 string，能过编译，但失去智能提示。想让 styles.primary 有类型、拼错时报错，就得为每个 CSS 文件配单独的 .d.ts。

• 例如 button.module.css 对应 button.module.css.d.ts：

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

• 这个文件必须和 CSS 文件同名、同目录，且不能有 declare module 包裹
• 缺点：手动维护成本高；优点：精准类型 + IDE 补全 + 拼写校验，适合核心组件库
• 自动化方案（如 typed-css-modules）已基本废弃，现代项目更倾向用基础声明 + CSS-in-JS 或 CSS Modules + PostCSS 插件生成类型

最易被忽略的一点：声明文件写了但没生效，大概率是因为它没被 TS 加载。检查 tsconfig.json 的 include 字段是否包含该 .d.ts 文件路径，或者是否被 exclude 误删。TS 不会自动扫描任意位置的 .d.ts，它只认配置范围内的。