HelloWorld 与 CSS Modules 使用教程

如果你只想知道怎么从零跑通一个 HelloWorld 并同时用上 CSS Modules：创建一个支持模块化 CSS 的项目（例如 Vite 或 Create React App），把样式文件命名为 *.module.css，然后在组件里 import styles from ‘./X.module.css’，把 className 设置为 styles.类名；需要自定义构建时，配置 css-loader 的 modules 选项或在 Vite 中直接使用默认行为。下面我会一步步拆开讲，既有最简单的 HelloWorld 示例，也会覆盖 webpack/Vite/TypeScript 配置、命名规范、组合与全局样式、常见坑与调试方法，让你能在真实项目中放心使用 CSS Modules。

为什么要用 CSS Modules？先用一句话说明

想避免样式冲突、让组件样式成为局部“私有域”，同时还能保持写普通 CSS 的体验。 传统全局 CSS 在大型项目里容易造成类名冲突、依赖隐式加载顺序，CSS Modules 的出现就是为了解决这些痛点：每个模块导出一个映射，把本地类名转换成带哈希的唯一标识，默认实现局部作用域。

先来一个最简单的 HelloWorld（React + Vite）

下面是最快速能跑起来的示例，适合初学者验证概念。

项目初始化（Vite）

• 运行：npm create vite@latest hello-css-modules — –template react
• 进入目录：cd hello-css-modules
• 安装依赖：npm install
• 启动：npm run dev

添加 CSS Module 文件

在 src 下创建 Hello.module.css 和 Hello.jsx：

/* Hello.module.css */
.title {
  color: #1e90ff;
  font-size: 28px;
  margin: 16px 0;
}
.subtitle {
  color: #333;
  font-size: 14px;
}

// Hello.jsx
import React from 'react';
import styles from './Hello.module.css';

export default function Hello() {
  return (
    <div>
      <h1 className={styles.title}>Hello World</h1>
      <p className={styles.subtitle}>这是 CSS Modules 的简单示例。</p>
    </div>
  );
}

在 Vite 和 CRA（Create React App）里，*.module.css 会被识别为模块化 CSS，直接运行就能看到效果。

深入理解：CSS Modules 的工作原理

核心思想是「本地作用域」。当你写 .title 时，构建工具会把它转换为类似 Hello_module__title__3X9ab 的类名，并把映射暴露给 JS（styles.title 指向这个唯一字符串）。因此组件可以通过 styles.title 使用样式，而不会影响其他组件。

生成规则与命名模板

不同构建工具会有不同的默认命名格式，常见格式示例：

• [name]__[local]___[hash:base64:5]
• [hash:base64:8]

可以在构建配置中自定义 localIdentName 来便于调试（开发环境下建议包含文件名与类名，生产环境用短哈希）。

在 webpack 中如何启用（关键配置）

如果你使用自定义 webpack，需要确保使用 css-loader 并开启 modules 选项；若还想提取成独立 CSS 文件，使用 MiniCssExtractPlugin。

// webpack.config.js（片段）
const MiniCssExtractPlugin = require('mini-css-extract-plugin');

module.exports = {
  module: {
    rules: [
      {
        test: /\.module\.(css|scss)$/,
        use: [
          MiniCssExtractPlugin.loader,
          {
            loader: 'css-loader',
            options: {
              modules: {
                localIdentName: '[name]__[local]___[hash:base64:5]'
              },
              importLoaders: 1
            }
          },
          'postcss-loader'
        ]
      },
      {
        test: /\.(css|scss)$/,
        exclude: /\.module\.(css|scss)$/,
        use: ['style-loader', 'css-loader', 'postcss-loader']
      }
    ]
  },
  plugins: [new MiniCssExtractPlugin()]
};

注意两条 rule 的区别：一个处理模块化文件（*.module.css），另一个处理全局样式。

在 TypeScript 中使用 CSS Modules

TypeScript 需要类型声明，否则 import styles 会报错。最简单的做法是在项目里加个全局声明文件。

// src/types/cssmodules.d.ts
declare module '*.module.css';
declare module '*.module.scss';

更进一步你可以用 typed-css-modules、css-modules-typescript-loader 或者 vite-plugin-dts 来生成更精确的类型定义（变量名自动补全）。

常见用法与技巧

• 动态类名：用 classnames 库或模板字符串将多个模块类组合起来。
• 组合（composes）：在一个模块里复用另一个模块的类。
• :global()：把某些选择器导出为全局样式（如 reset 或第三方库 hook）。
• Sass / Less 支持：同样命名为 *.module.scss/.module.less 即可，构建工具需配置对应 loader。

动态类名示例

// 使用 classnames
import cn from 'classnames';
import styles from './Button.module.css';

function Button({ active }) {
  return <button className={cn(styles.btn, { [styles.active]: active })}>OK</button>;
}

composes 示例

/* base.module.css */
.base {
  padding: 8px 12px;
  border-radius: 4px;
}

/* primary.module.css */
.primary {
  composes: base from './base.module.css';
  background: #1e90ff;
  color: #fff;
}

composes 可以从同一模块或其他模块继承样式，但要注意构建工具对路径与 loader 的支持。

:global 使用场景

/* globals.module.css */
:global(.reset) {
  margin: 0;
  padding: 0;
}

当你需要定义复位样式或与第三方插件/HTML 元素进行样式匹配时，可以用 :global()。但尽量少用，保持模块化的好处。

对比表：全局 CSS vs CSS Modules

常见问题与排查方法

• 样式没有生效：确认文件名是否以 .module.css 结尾，且在构建链中被模块化规则处理；检查 import 的路径拼写。
• 类名是 [object Object]：通常是因为没正确 import，或使用了 CSS Modules 的默认导出结构不对（例如用 require 语法或 loader 配置差异）。
• 服务端渲染（SSR）类名不一致：要确保构建时的 localIdentName 在服务端和客户端一致，或者在 SSR 时使用相同的哈希种子。
• composes 无效或报错：确认 css-loader 支持并且允许从外部文件 composes；某些 loader 版本或配置会影响。
• 第三方库样式需要全局：将它们放到独立的全局 CSS（非 module），或用 :global() 包裹必要选择器。

生产环境注意事项

• 将 localIdentName 缩短为哈希以减小输出体积并隐藏实现细节，例如 [hash:base64:8]。
• 把公共 reset、字体、第三方样式提取为全局文件，只在入口处加载一次。
• 使用 MiniCssExtractPlugin 或类似插件把 CSS 抽取成单独文件，避免 style-loader 在生产里注入太多内联样式。这样有利于缓存与性能。

进阶技巧与模式

模块化 + 原子化结合

把常用的工具类（margin/padding/typo）放到一个全局 util.css，然后让组件样式仅负责结构与状态。这样在需要快速布局时，可以复用工具类，同时保持组件样式私有。

命名策略

建议使用简洁有意义的本地类名（例如 title, container, item），配合文件名就能表达语义；若喜欢约定式可以使用 BEM 风格：block__element–modifier，这样在调试映射时更易读。

样式复用与抽象

当多个组件共享相同视觉规范（例如按钮样式），可以把基础样式抽成 base.module.css 并用 composes 或在 JS 层组合多个模块导出的类名。

完整示例：从零到有（包括 webpack 配置与 TypeScript）

下面是一个较完整的流程梳理，按步骤操作能在自定义 webpack 项目里稳定运行：

1. 初始化项目：npm init -y，安装 react/react-dom（或其他框架）。
2. 安装构建工具与 loader：webpack、webpack-cli、css-loader、style-loader 或 MiniCssExtractPlugin、postcss-loader（如需）。
3. 添加规则：对 *.module.css 启用 css-loader modules 选项；对其他 css 文件保持全局处理。
4. 在组件中 import styles from ‘./X.module.css’ 并使用 styles.xxx。
5. 测试开发服务器，检查生成的 class 名是否带有哈希，调试样式是否被应用。
6. 在 TypeScript 中添加声明文件避免类型错误。

实用小贴士（写给会边做边学的人）

• 开发时把 localIdentName 设得可读一些，方便浏览器调试；生产构建再切换到短哈希。
• 不要把大量全局样式放进模块文件：模块越大，维护成本越高。
• 在组件库里使用 CSS Modules 时，考虑对外暴露样式 API（例如提供 className 入口）以便消费者覆盖。
• 遇到奇怪的问题先怀疑构建链：loader 顺序、缓存、node_modules 中的样式导入都会影响结果。

参考与延伸阅读（书名/项目名）

• 官方 css-modules README
• webpack 文档：css-loader options
• Vite 文档：CSS Modules 支持说明
• 有关组件样式体系的文章与实践（可查阅“构建可维护的 CSS”类书籍）

如果你现在想立刻把示例跑起来，按照前面的 Vite 快速示例操作，注意文件名以 .module.css 结尾，然后在组件里 import 并使用样式。遇到问题就从文件命名、构建规则、以及开发/生产的 localIdentName 三个方向排查，通常能很快定位。说完这些，我也觉得每次配置完看到浏览器里干净的类名映射那一刻挺有成就感的——不过实际项目里总会有例外，需要折腾几下才顺手。