下面给出一套可直接落地的 Webpack 5 配置方案，面向 TypeScript + React 的单页应用（SPA），满足以下目标：
- 代码分包与长期缓存（contenthash、SplitChunks、runtime 分离、deterministic ids）
- 区分开发/生产配置（webpack-merge）
- 启用 Tree Shaking 与 SourceMap
- 自动注入环境变量（限定前缀，避免泄露）
- 生成 CI 可用构建产物（stats、manifest、可选压缩）
- 可扩展与可维护（分层配置、约定目录、路径别名）
一、目录结构建议
- package.json
- tsconfig.json
- babel.config.js
- postcss.config.js
- .browserslistrc
- .env.example
- public/
- src/
- index.tsx
- App.tsx
- pages/...
- styles/...
- webpack/
- utils/
- webpack.common.js
- webpack.dev.js
- webpack.prod.js
二、依赖（精简清单）
- webpack 核心：webpack webpack-cli webpack-dev-server webpack-merge
- 加载器与语言：babel-loader @babel/core @babel/preset-env @babel/preset-react @babel/preset-typescript typescript
- React HMR：react-refresh @pmmmwh/react-refresh-webpack-plugin
- 样式与 PostCSS：style-loader css-loader postcss-loader postcss postcss-preset-env autoprefixer mini-css-extract-plugin css-minimizer-webpack-plugin
- 资源与优化：html-webpack-plugin terser-webpack-plugin webpack-manifest-plugin
- 工具：dotenv dotenv-expand cross-env fork-ts-checker-webpack-plugin tsconfig-paths-webpack-plugin
- 可选：compression-webpack-plugin（CI 产物压缩）
三、package.json（摘取关键）
{
"scripts": {
"start": "cross-env NODE_ENV=development webpack serve --config webpack/webpack.dev.js",
"build": "cross-env NODE_ENV=production webpack --config webpack/webpack.prod.js",
"build:stats": "cross-env NODE_ENV=production webpack --config webpack/webpack.prod.js --profile --json > build/stats.json",
"typecheck": "tsc -p tsconfig.json --noEmit",
"analyze": "cross-env ANALYZE=true npm run build"
},
"sideEffects": [".css", ".scss"],
"browserslist": [
"defaults",
"not IE 11",
"maintained node versions"
]
}
说明：
- sideEffects 声明使 JS 支持 Tree Shaking，同时保留对样式资源的副作用声明。
- 使用 cross-env 确保跨平台 NODE_ENV 一致。
- build:stats 生成 CI 可分析的 stats.json。
四、tsconfig.json（确保支持 Tree Shaking 与路径别名）
{
"compilerOptions": {
"target": "ES2018",
"lib": ["ES2018", "DOM"],
"module": "ESNext",
"moduleResolution": "Bundler",
"jsx": "react-jsx",
"strict": true,
"noEmit": true,
"baseUrl": ".",
"paths": {
"@/": ["src/"]
},
"resolveJsonModule": true,
"isolatedModules": true,
"skipLibCheck": true
},
"include": ["src"]
}
五、babel.config.js（React + TS + 按需 polyfill）
module.exports = function (api) {
const isProd = api.env('production');
const isTest = api.env('test');
return {
presets: [
["@babel/preset-env", {
targets: ">0.2%, not dead, not op_mini all",
useBuiltIns: "usage",
corejs: 3
}],
["@babel/preset-react", { runtime: "automatic", development: !isProd }],
["@babel/preset-typescript", { allowDeclareFields: true }]
],
plugins: [
!isProd && "react-refresh/babel"
].filter(Boolean),
assumptions: { setPublicClassFields: true }
};
};
六、postcss.config.js
module.exports = {
plugins: [
require("postcss-preset-env")({ stage: 3 }),
require("autoprefixer")
]
};
七、.browserslistrc（可与 package.json 中 browserslist 二选一）
0.2%
not dead
not op_mini all
八、环境变量约定
九、webpack/utils/env.js（统一加载并筛选环境变量）
const fs = require("fs");
const path = require("path");
const dotenv = require("dotenv");
const dotenvExpand = require("dotenv-expand");
function loadEnv(mode) {
const base = path.resolve(process.cwd(), ".env");
const modeFile = ${base}.${mode};
const files = [base, modeFile].filter(fs.existsSync);
let env = {};
files.forEach((file) => {
const result = dotenv.config({ path: file });
dotenvExpand.expand(result);
Object.assign(env, result.parsed || {});
});
// 从 process.env 合并，CI 中常用
Object.keys(process.env).forEach((k) => {
if (!(k in env)) env[k] = process.env[k];
});
// 仅暴露 PUBLIC_ 开头的键
const raw = Object.keys(env)
.filter((k) => /^PUBLIC_/i.test(k))
.reduce((acc, k) => ((acc[k] = env[k]), acc), {});
// 供 DefinePlugin 使用
const stringified = Object.keys(raw).reduce((acc, k) => {
acc[process.env.${k}] = JSON.stringify(raw[k]);
return acc;
}, { "process.env.NODE_ENV": JSON.stringify(mode) });
return { raw, stringified };
}
module.exports = { loadEnv };
十、webpack/webpack.common.js（基础配置）
const path = require("path");
const HtmlWebpackPlugin = require("html-webpack-plugin");
const { DefinePlugin } = require("webpack");
const { loadEnv } = require("./utils/env");
const ForkTsCheckerWebpackPlugin = require("fork-ts-checker-webpack-plugin");
const TsconfigPathsPlugin = require("tsconfig-paths-webpack-plugin");
const { WebpackManifestPlugin } = require("webpack-manifest-plugin");
module.exports = (env, argv) => {
const mode = argv.mode || process.env.NODE_ENV || "development";
const isProd = mode === "production";
const { stringified } = loadEnv(mode);
return {
mode,
entry: path.resolve(__dirname, "../src/index.tsx"),
output: {
path: path.resolve(__dirname, "../dist"),
filename: isProd ? "js/[name].[contenthash:8].js" : "js/[name].js",
chunkFilename: isProd ? "js/[name].[contenthash:8].chunk.js" : "js/[name].chunk.js",
assetModuleFilename: "assets/[name].[contenthash:8][ext]",
publicPath: "/",
clean: true
},
resolve: {
extensions: [".tsx", ".ts", ".jsx", ".js", ".json"],
plugins: [new TsconfigPathsPlugin()]
},
cache: {
type: "filesystem",
buildDependencies: { config: [__filename] }
},
module: {
rules: [
{
test: /.[jt]sx?$/,
include: path.resolve(dirname, "../src"),
use: [
{
loader: "babel-loader",
options: {
cacheDirectory: true,
cacheCompression: false
}
}
]
},
// CSS Modules
{
test: /.module.css$/,
use: [
isProd ? require("mini-css-extract-plugin").loader : "style-loader",
{
loader: "css-loader",
options: {
modules: {
localIdentName: isProd ? "[hash:base64:8]" : "[path][name][local]"
},
importLoaders: 1
}
},
"postcss-loader"
]
},
// 全局 CSS
{
test: /.css$/,
exclude: /.module.css$/,
use: [
isProd ? require("mini-css-extract-plugin").loader : "style-loader",
"css-loader",
"postcss-loader"
]
},
// 资源模块
{
test: /.(png|jpe?g|gif|svg|webp|avif)$/i,
type: "asset",
parser: { dataUrlCondition: { maxSize: 8 * 1024 } }
},
{ test: /.(woff2?|ttf|eot|otf)$/i, type: "asset/resource" }
]
},
plugins: [
new HtmlWebpackPlugin({
template: path.resolve(__dirname, "../public/index.html"),
favicon: path.resolve(__dirname, "../public/favicon.ico"),
inject: "body"
}),
new DefinePlugin(stringified),
new ForkTsCheckerWebpackPlugin({ async: !isProd }),
new WebpackManifestPlugin({ fileName: "asset-manifest.json", publicPath: "/" })
]
};
};
十一、webpack/webpack.dev.js（开发配置）
const { merge } = require("webpack-merge");
const ReactRefreshWebpackPlugin = require("@pmmmwh/react-refresh-webpack-plugin");
const common = require("./webpack.common");
module.exports = (env, argv) => merge(common(env, argv), {
mode: "development",
devtool: "cheap-module-source-map",
devServer: {
port: 3000,
open: true,
hot: true,
historyApiFallback: true,
compress: true,
client: { overlay: { errors: true, warnings: false } },
static: { directory: "public", watch: true }
},
plugins: [new ReactRefreshWebpackPlugin()],
optimization: {
runtimeChunk: "single"
}
});
十二、webpack/webpack.prod.js（生产配置：长期缓存、分包、压缩与 SourceMap）
const { merge } = require("webpack-merge");
const common = require("./webpack.common");
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
const CssMinimizerPlugin = require("css-minimizer-webpack-plugin");
const TerserPlugin = require("terser-webpack-plugin");
// 可选 gzip/brotli 压缩
// const CompressionPlugin = require("compression-webpack-plugin");
const isAnalyze = process.env.ANALYZE === "true";
module.exports = (env, argv) => merge(common(env, argv), {
mode: "production",
devtool: process.env.SOURCE_MAP === "hidden" ? "hidden-source-map" : "source-map",
output: {
filename: "js/[name].[contenthash:8].js",
chunkFilename: "js/[name].[contenthash:8].chunk.js"
},
plugins: [
new MiniCssExtractPlugin({
filename: "css/[name].[contenthash:8].css",
chunkFilename: "css/[name].[contenthash:8].chunk.css"
})
// new CompressionPlugin({ algorithm: "brotliCompress", filename: "[path][base].br" }),
// new CompressionPlugin({ algorithm: "gzip", filename: "[path][base].gz" })
],
optimization: {
minimize: true,
minimizer: [
new TerserPlugin({
extractComments: false,
terserOptions: {
safari10: true,
compress: { passes: 2, pure_getters: true, drop_console: !!process.env.DROP_CONSOLE }
}
}),
new CssMinimizerPlugin()
],
moduleIds: "deterministic",
chunkIds: "deterministic",
runtimeChunk: "single",
splitChunks: {
chunks: "all",
minSize: 20_000,
cacheGroups: {
// 将第三方依赖抽到 vendor
vendor: {
test: /[\/]node_modules[\/]/,
name: "vendors",
priority: -10,
reuseExistingChunk: true
},
// 可选：单独拆出 React 生态，保持更稳定的缓存
react: {
test: /[\/]node_modules\/[\/]/,
name: "react-vendor",
priority: 10,
enforce: true
}
}
}
},
performance: {
hints: false
}
});
说明：
- runtimeChunk: single + deterministic ids + contenthash，确保长期缓存稳定。
- splitChunks 将第三方依赖与应用代码分开，React 生态单独抽取可提升缓存命中。
- SourceMap 默认 source-map，若不想对外暴露映射，可用 SOURCE_MAP=hidden 切换为 hidden-source-map。
十三、public/index.html（模板要有根节点）
App
十四、src/index.tsx（示例：动态 import 触发代码分包）
import React, { Suspense } from "react";
import { createRoot } from "react-dom/client";
const App = React.lazy(() => import("./App"));
createRoot(document.getElementById("root")!).render(
<Suspense fallback={
Loading...
}>
);
十五、关键点解释与落地建议
- Tree Shaking
- 使用 "module": "ESNext" 以保留 ESM 供 Webpack 分析。
- 在 package.json 声明 sideEffects，避免误删样式副作用。
- 生产模式会自动启用 usedExports、minimize 与 DCE。
- SourceMap
- 开发：cheap-module-source-map（与 HMR 兼容、速度快）。
- 生产：source-map（CI/定位问题）；若不想暴露，切换为 hidden-source-map。
- 环境变量
- 仅注入以 PUBLIC_ 开头变量，避免泄露服务端敏感信息。
- 可在 CI 中通过环境注入（如 GitHub Actions 的 env）直接覆盖。
- 长期缓存
- contenthash 文件名、deterministic ids、runtime 分离、稳定的 vendor/react-vendor 拆分。
- 升级依赖时尽量锁版本，避免 vendor 内容频繁变化。
- 构建性能
- filesystem cache + babel-loader cacheDirectory。
- TypeScript 类型检查通过 ForkTsChecker 并行执行，不阻塞打包。
- CI 产物与可观测性
- dist/ 为可部署产物；asset-manifest.json 用于服务端注入或调试；build:stats 生成 stats.json 供分析。
- 可选启用 gzip/brotli 生成预压缩包（Nginx/CDN 可直接回源使用）。
- 可扩展与可维护
- 按 common/dev/prod 分层，env 工具模块化，后续扩展（如 SASS、SVG ReactComponent、Module Federation）只需在 common 中增加 loader/插件或新增特定配置。
- 使用 TsconfigPathsPlugin 与路径别名提升可维护性。
十六、常见拓展（可选）
- SCSS：在 CSS 规则中加上 sass-loader，并在 sideEffects 中包含 *.scss。
- Bundle 分析：ANALYZE=true 时接入 webpack-bundle-analyzer。
- Sentry：使用 @sentry/webpack-plugin 上传 source maps；配合 hidden-source-map。
- PWA：结合 workbox-webpack-plugin 生成 service worker。
至此，该配置即满足：
- 分包与长期缓存（contenthash、splitChunks、runtime 分离、deterministic ids）
- 开发/生产区分（merge 与独立文件）
- Tree Shaking 与 SourceMap
- 环境变量安全注入（PUBLIC_ 前缀）
- CI 可用产物（dist、asset-manifest.json、stats.json、可选压缩）
- 结构清晰，便于扩展维护。
