基于路由的代码分割引发CSS chunk重复问题，求解决方案

问题描述 #

基于路由的代码分割会导致公共组件的CSS在多个代码块（chunk）中重复打包，进而可能引发意外的样式覆盖问题。

复现步骤 #

• 使用create-react-app创建简单应用
• 采用react-router-dom实现客户端路由
• 添加一个带有本地CSS的公共组件
• 创建两个页面，引入该公共组件并覆盖其样式
• 执行build命令
• 查看static文件夹

相关代码示例 #

公共组件样式文件 (/components/CommonPageHeader/CommonPageHeader.module.scss) #

.header {
  color: black;
}

公共组件代码 (/components/CommonPageHeader/CommonPageHeader.tsx) #

import styles from "./CommonPageHeader.module.scss";
import { ReactNode } from "react";

export const CommonPageHeader = (props: {
  className: string;
  children: ReactNode;
}) => {
  const { className = "", children } = props;

  return <h1 className={`${styles.header} ${className}`}>{children}</h1>;
};

首页样式文件 (/pages/Home/Home.module.scss) #

.greenHeader {
  color: green;
}

首页代码 (/pages/Home/Home.tsx) #

import React from "react";
import { Link } from "react-router-dom";
import { CommonPageHeader } from "../../components/CommonPageHeader/CommonPageHeader";
import styles from "./Home.module.scss";

const Home = () => (
  <>
    <CommonPageHeader className={styles.greenHeader}>
      我是绿色标题
    </CommonPageHeader>
    <Link to="some-page">跳转至其他页面</Link>
  </>
);
export default Home;

其他页面样式文件 (/pages/SomePage/SomePage.module.scss) #

.redHeader {
  color: red;
}

其他页面代码 (/pages/SomePage/SomePage.tsx) #

import React from "react";
import { Link } from "react-router-dom";
import { CommonPageHeader } from "../../components/CommonPageHeader/CommonPageHeader";
import styles from "./SomePage.module.scss";

const SomePage = () => {
  return (
    <>
      <CommonPageHeader className={styles.redHeader}>
        我是红色标题
      </CommonPageHeader>
      <Link to="/">返回首页</Link>
    </>
  );
};
export default SomePage;

路由配置 (index.tsx) #

import React, { Suspense } from "react";
import ReactDOM from "react-dom/client";
import { createBrowserRouter, RouterProvider } from "react-router-dom";

const Home = React.lazy(() => import("./pages/Home/Home"));
const SomePage = React.lazy(() => import("./pages/SomePage/SomePage"));

const router = createBrowserRouter([
  {
    path: "/",
    element: (
      <Suspense>
        <Home />
      </Suspense>
    ),
  },
  {
    path: "/some-page",
    element: (
      <Suspense>
        <SomePage />
      </Suspense>
    ),
  },
]);

const root = ReactDOM.createRoot(
  document.getElementById("root") as HTMLElement
);
root.render(
  <React.StrictMode>
    <RouterProvider router={router} />
  </React.StrictMode>
);

生产环境问题表现 #

构建后，公共组件的CSS会被重复打包到多个CSS chunk中：

/build/static/css/499.408c3ff0.chunk.css #

.CommonPageHeader_header__eTauC {
    color: #000
}

.Home_greenHeader__YwF4H {
    color: green
}

/build/static/css/136.855973ab.chunk.css #

.CommonPageHeader_header__eTauC {
    color: #000
}

.SomePage_redHeader__a-I8c {
    color: red
}

解决方案 #

1. 配置Webpack拆分公共CSS chunk #

如果使用eject后的Create React App或自定义Webpack配置，可通过splitChunks将公共组件的CSS提取到单独chunk：

module.exports = {
  optimization: {
    splitChunks: {
      cacheGroups: {
        sharedComponents: {
          test: /[\\/]components[\\/]/,
          name: "shared-components",
          chunks: "all",
          enforce: true,
        },
      },
    },
  },
};

2. 改用CSS-in-JS方案 #

使用Styled Components、Emotion等CSS-in-JS库，样式会与组件逻辑绑定，代码分割时不会出现重复打包，样式随组件动态注入。

3. 预加载公共样式 #

将公共组件的CSS在入口文件中提前引入，确保只被打包一次。此方法会增加初始加载体积，适合公共样式体积较小的场景。

4. 使用React Router布局组件包裹公共组件 #

将公共组件放在路由的布局组件中，通过Outlet渲染页面内容，确保公共组件仅加载一次：

// Layout.tsx
import { Outlet } from "react-router-dom";

export const Layout = () => (
  <>
    {/* 公共组件仅在此处渲染一次 */}
    <Outlet />
  </>
);

// index.tsx
const router = createBrowserRouter([
  {
    element: <Layout />,
    children: [
      { path: "/", element: <Home /> },
      { path: "/some-page", element: <SomePage /> },
    ],
  },
]);

内容的提问来源于stack exchange，提问作者Miroslav Petrov