Symfony Webpack Encore 中 React 组件 CSS 模块化实践指南

问题背景

在 Symfony 项目中使用 Webpack Encore 构建工具时，开发者经常会遇到一个典型问题：如何在 React 组件中正确导入和使用 CSS/SCSS 样式文件。许多开发者尝试直接在组件中通过 import './styles.scss' 的方式引入样式，却发现样式并未生效。

核心问题分析

通过深入分析，我们发现这个问题通常由两个关键因素导致：

1. CSS 模块化配置不当：Webpack 需要正确配置 CSS 模块化处理规则
2. 资源输出引用缺失：生成的 CSS 文件未被正确引入到最终 HTML 中

解决方案详解

1. 正确配置 CSS 模块化

首先需要在 webpack.config.js 中正确配置 CSS 模块化处理规则：

.enableSassLoader()
.configureCssLoader(options => {
    options.modules = {
        auto: (resourcePath) => {
            // 仅在特定路径下启用 CSS 模块化
            return resourcePath.includes(path.join('assets', 'react'))
        }
    };
})

2. 组件中正确导入样式

在 React 组件中，推荐使用以下两种方式导入样式：

方式一：命名导入

import * as styles from './calendar.scss?module';
// 使用方式
<div className={styles.tsCalendar}>

方式二：默认导入（需额外配置）

import styles from './calendar.scss?module';
// 使用方式
<div className={styles.tsCalendar}>

要使默认导入方式生效，需要在 configureCssLoader 中添加：

options.modules.namedExport = false;

3. 类型声明支持（TypeScript 项目）

对于使用 TypeScript 的项目，需要添加类型声明文件（如 styles.d.ts）：

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

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

4. 确保样式文件被正确引入

最关键但常被忽视的一步是确保生成的 CSS 文件被正确引入到 HTML 中。在 Symfony 的 Twig 模板中需要同时添加：

{{ encore_entry_script_tags('appJS') }}
{{ encore_entry_link_tags('appJS') }}

最佳实践建议

1. 样式作用域：建议将 CSS 模块化限制在 React 组件目录下，避免影响全局样式
2. 命名规范：使用 camelCase 命名样式类，便于在 JavaScript 中引用
3. 开发环境优化：在开发环境下可使用 style-loader 实现热更新，生产环境使用 mini-css-extract-plugin
4. 样式隔离：考虑使用 BEM 或其他命名约定避免样式冲突

总结

在 Symfony 项目中使用 Webpack Encore 配合 React 开发时，正确处理 CSS 模块化需要关注配置、导入方式和最终输出三个关键环节。通过正确配置 CSS 加载器、使用模块化导入语法以及确保样式文件被正确引入，可以构建出既模块化又高效的样式系统。这种方案不仅解决了样式隔离问题，还能与现代前端开发工作流完美融合。