深入理解 Webpack 核心配置结构

type EntryDescription = {
  import: string | string[] | (() => string | string[] | Promise<string | string[]>);
  filename?: string;
  dependOn?: string | string[];
  library?: LibraryOptions | Libraryname;
  runtime?: string | false;
  baseHref?: string;
  publicPath?: string;
  chunkLoading?: false | 'jsonp' | 'import-scripts' | 'require' | 'async-node';
  asyncChunks?: boolean;
};

type EntryDynamic =
  | string
  | string[]
  | { [entryChunkName: string]: string | string[] | EntryDescription }
  | (() => EntryDynamic | Promise<EntryDynamic>);

// 类型: string
module.exports = {
  entry: './src/index.js'
};

entry: {
  main: './src/index.js'
}

// 类型: string[]
module.exports = {
  entry: ['./src/polyfills.js', './src/index.js']
};

entry: {
  main: ['./src/polyfills.js', './src/index.js']
}

module.exports = {
  entry: {
    // === 基础字符串值 ===
    home: './src/home.js',

    // === 数组值（预依赖）===
    shared: ['react', 'react-dom', 'redux'],

    // === EntryDescription 对象（完整控制）===
    personal: {
      import: './src/personal.js',
      filename: 'pages/[name].js',
      dependOn: 'shared',
      chunkLoading: 'jsonp',
      asyncChunks: true,
    },

    // === 函数形态（动态计算）===
    admin: () => './src/admin.js',

    // === 异步函数（远程获取入口）===
    dashboard: async () => {
      const { default: entries } = await fetch('https://api.example.com/entries');
      return entries.dashboard;
    }
  },
};

// 同步函数
module.exports = {
  entry: () => './src/index.js'
};

// 异步函数（支持远程获取）
module.exports = {
  entry: async () => {
    const config = await fetch('./entry-config.json').then(r => r.json());
    return config.entries;
  }
};

// 返回对象
module.exports = {
  entry: () => ({
    main: './src/index.js',
    admin: './src/admin.js'
  })
};

module.exports = async function(env, argv) {
  // env: --env 传入的自定义参数
  // argv: CLI 参数（如 --mode, --config-name）
  return {
    entry: {
      main: argv.mode === 'production'
        ? './src/index.prod.js'
        : './src/index.dev.js'
    }
  };
}

module.exports = {
  entry: {
    // 主入口：包含框架代码 + 运行时
    vendor: {
      import: ['react', 'react-dom', 'lodash'],
      filename: 'vendor.[contenthash:8].js',
    },

    // 页面A：依赖 vendor，只包含页面特有代码
    pageA: {
      import: './src/pages/pageA.js',
      dependOn: 'vendor',
      filename: 'pageA.[contenthash:8].js',
    },

    // 页面B：同样依赖 vendor
    pageB: {
      import: './src/pages/pageB.js',
      dependOn: 'vendor',
      filename: 'pageB.[contenthash:8].js',
    },
  },
};

module.exports = {
  entry: {
    main: {
      import: './src/main.js',
      runtime: 'shared-runtime',  // 运行时抽取到 shared-runtime
    },
    about: {
      import: './src/about.js',
      runtime: 'shared-runtime',   // 同一个 runtime chunk
    },
    contact: {
      import: './src/contact.js',
      runtime: false,              // 内联运行时（不抽取）
    },
  },
  output: {
    filename: '[name].[contenthash:8].js',
  },
};

const path = require('path');

module.exports = {
  mode: 'production',

  entry: {
    // 主应用入口
    main: {
      import: ['./src/polyfills.ts', './src/main.tsx'],
      filename: 'js/app.[contenthash:8].js',
    },

    // 管理后台（独立入口）
    admin: {
      import: './src/admin.tsx',
      filename: 'js/admin.[contenthash:8].js',
      dependOn: 'main',
    },

    // SSR 入口（Node.js 环境）
    ssr: {
      import: './src/ssr.tsx',
      filename: 'ssr/bundle.js',
      library: { type: 'commonjs2' },
      runtime: false,
    },
  },

  output: {
    path: path.resolve(__dirname, 'dist'),
    publicPath: 'https://cdn.example.com/',
    clean: true,
  },
};

interface Output {
  // === 基础路径 ===
  path: string;
  publicPath?: string;

  // === 文件名模板 ===
  filename?: string | ((pathData: PathData, assetInfo?: AssetInfo) => string);
  chunkFilename?: string;
  cssFilename?: string;          // v5.107+
  cssChunkFilename?: string;     // v5.107+
  assetModuleFilename?: string;

  // === 输出格式 ===
  module?: boolean;               // v5.107+: ESM 输出
  library?: LibraryOptions | string;
  libraryExport?: string;         // 已废弃，使用 library.export
  libraryTarget?: string;         // 已废弃，使用 library.type
  libraryUniqueName?: boolean;
  chunkFormat?: 'array-push' | 'commonjs' | 'module' | 'array-push-with-web-worker';

  // === 异步加载 ===
  chunkLoading?: false | 'jsonp' | 'import-scripts' | 'require' | 'async-node';
  chunkLoadTimeout?: number;
  chunkLoadingGlobal?: string;

  // === 清理与环境 ===
  clean?: CleanOptions | boolean;
  environment?: Environment;
  compareBeforeEmit?: boolean;    // v5.107+

  // === 其他 ===
  uniqueName?: string;
  crossOriginLoading?: false | 'anonymous' | 'use-credentials';
  charset?: boolean;
  sourceMapFilename?: string;
  devtoolModuleFilenameTemplate?: string | ((info: object) => string);
  devtoolFallbackModuleFilenameTemplate?: string | ((info: object) => string);
  strictModuleExceptionHandling?: boolean;
  globalObject?: string;
  importFunctionName?: string;
  importMetaName?: string;
  scriptType?: false | 'text/javascript' | 'module';
  enabledLibraryTypes?: string[];
  trustedTypes?: TrustedTypesPolicyOptions;
  workerPublicPath?: string;
  asyncChunks?: boolean;
  wasmLoading?: 'fetch' | 'async-node';
}

const path = require('path');

module.exports = {
  output: {
    path: path.resolve(__dirname, 'dist/release'),
  },
};

output: {
  filename: (pathData) => {
    if (pathData.chunk.name === 'admin') {
      return 'admin/[name].[contenthash:8].js';
    }
    return '[name].[contenthash:8].js';
  },
},

output: {
  filename: isDev
    ? 'js/[name].js'
    : 'js/[name].[contenthash:8].js',
  chunkFilename: isDev
    ? 'js/[name].chunk.js'
    : 'js/[name].[contenthash:8].chunk.js',
}

// 传统 CommonJS/IIFE 输出 (module: false)
(function(modules) {
  var installedModules = {};
  function __webpack_require__(moduleId) { /* ... */ }
  __webpack_require__.m = modules;
  __webpack_require__.c = installedModules;
  // ... 大量运行时代码
})({"./src/index.js": (function(module, exports, __webpack_require__) {
  eval("...");
})});

// ESM 输出 (module: true)
import { __webpack_require__, __webpack_modules__ } from "webpack-bootstrap";
var __webpack_exports__ = {};
import { foo } from "./foo.js";
__webpack_exports__.default = /* ... */;
export default __webpack_exports__;

// 完整启用示例
module.exports = {
  experiments: { outputModule: true },
  output: {
    filename: '[name].mjs',
    module: true,
    library: {
      type: 'module',
      name: 'MyLib',
    },
  },
};

output: {
  clean: true,  // 每次构建清空 dist 目录
}

output: {
  clean: {
    dry: false,                    // 干跑模式：只记录不删除
    keep: /\/assets/,              // 保留匹配的文件/目录
    keepStaticAssets: true,        // 保留静态资源
    manifest: 'clean-manifest.json', // 输出被删除文件的清单
  },
}

{
  "deleted": [
    "dist/js/main.a1b2c3d4.js",
    "dist/js/vendor.e5f6g7h8.js",
    "dist/index.html"
  ],
  "kept": [
    "dist/assets/logo.png",
    "dist/static/favicon.ico"
  ]
}

interface Environment {
  arrowFunction?: boolean;
  bigIntLiteral?: boolean;
  const?: boolean;
  destructuring?: boolean;
  forOf?: boolean;
  dynamicImport?: boolean;
  dynamicImportInWorker?: boolean;
  module?: boolean;
  optionalChaining?: boolean;
  templateLiteral?: boolean;
  nullishCoalescingOperator?: boolean;
  objectAssign?: boolean;
  typeofUndefined?: boolean;
  document?: boolean;
  globalThis?: boolean;
  fetch?: boolean;
  importedMeta?: boolean;
  writableImports?: boolean;
  topLevelAwait?: boolean;
}

output: {
  environment: {
    // 目标环境不支持这些语法，Webpack 会进行转换
    arrowFunction: false,
    const: false,
    destructuring: false,
    bigIntLiteral: false,

    // 目标环境支持这些，无需转换
    templateLiteral: true,
    optionalChaining: true,
    nullishCoalescingOperator: true,
  },
}

module.exports = {
  experiments: { css: true },
  output: {
    cssFilename: 'static/css/[name].[contenthash:8].css',
    cssChunkFilename: 'static/css/[name].[contenthash:8].chunk.css',
  },
};

output: {
  library: {
    name: 'MyLibrary',           // 库名称
    type: 'umd',                 // 输出格式
    export: 'default',           // 导出的内容
    auxiliaryComment: {          // 注释
      root: 'Root Export',
      commonjs: 'CommonJS Export',
      commonjs2: 'CommonJS2 Export',
      amd: 'AMD Export',
    },
    umdNamedDefine: true,        // UMD 命名 define
    exportToGlobal: true,        // 同时挂载到全局
  },
}

output: {
  compareBeforeEmit: true,  // CI 场景强烈推荐
}

const path = require('path');

module.exports = {
  output: {
    // === 路径 ===
    path: path.resolve(__dirname, 'dist'),
    publicPath: process.env.CDN_URL | | '/',

    // === 文件名 ===
    filename: isDev
      ? 'js/[name].js'
      : 'js/[name].[contenthash:8].js',
    chunkFilename: isDev
      ? 'js/chunks/[name].chunk.js'
      : 'js/chunks/[name].[contenthash:8].chunk.js',
    assetModuleFilename: 'assets/[hash][ext][query]',

    // === CSS（需配合 experiments.css）===
    ...(hasCssExperiment ? {
      cssFilename: 'static/css/[name].[contenthash:8].css',
      cssChunkFilename: 'static/css/[name].[contenthash:8].chunk.css',
    } : {}),

    // === 格式 ===
    module: enableESMOutput,
    chunkFormat: 'array-push',
    chunkLoading: 'jsonp',

    // === 清理 ===
    clean: isDev ? false : {
      keep: /\/assets/,
      manifest: '.cache/clean-manifest.json',
    },

    // === 环境 ===
    environment: {
      arrowFunction: targetSupportsArrowFn,
      const: !targetSupportsConstLet,
      destructuring: !targetSupportsDestructuring,
      bigIntLiteral: false,
      optionalChaining: targetSupportsOptionalChaining,
      nullishCoalescingOperator: targetSupportsNullishCoalescing,
    },

    // === 性能 ===
    compareBeforeEmit: !isDev,

    // === 库模式（如需要）===
    ...(isLibraryBuild ? {
      library: {
        name: pkg.name.replace(/[^a-zA-Z0-9-_]/g, ''),
        type: 'umd',
        export: 'default',
      },
    } : {}),

    // === 其他 ===
    charset: true,
    crossOriginLoading: 'anonymous',
    uniqueName: 'my-app-v1',
  },
};

interface Resolve {
  // === 扩展名解析 ===
  extensions?: string[];                    // 默认: ['.js', '.json', '.wasm']

  // === 路径别名 ===
  alias?: Record<string, string | false | string[]> | AliasOption[];

  // === 模块搜索目录 ===
  modules?: string[];                       // 默认: ['node_modules']

  // === 主字段解析 ===
  mainFields?: string[];                    // 默认因 target 不同而不同
  mainFiles?: string[];                     // 默认: ['index']

  // === Package Exports（v5+）===
  exportsFields?: string[];                 // 默认: ['exports']
  importsFields?: string[];                 // 默认: ['imports']
  conditionNames?: string[];

  // === 按依赖类型差异化解析 ===
  byDependency?: Record<string, Partial<Resolve>>;

  // === Node.js Polyfill ===
  fallback?: Record<string, string | false>;

  // === TypeScript（v5.105+）===
  tsconfig?: string | TsconfigOptions;

  // === 解析行为控制 ===
  symlinks?: boolean;                       // 默认: true
  enforceExtension?: boolean;               // 默认: false
  enforceRelativeExtension?: boolean;       // 默认: false
  cacheWithContext?: boolean;               // 默认: true (v5 中已移除)
  preferRelative?: boolean;                 // 默认: false
  preferAbsolute?: boolean;                 // 默认: false

  // === 插件 ===
  plugins?: any[];

  // === Loader 专用解析 ===
  resolver?: any;
}

interface TsconfigOptions {
  configFile?: string;
  extensions?: ReadonlyArray<string>;
  onlyImplicitDependenciesFor?: ReadonlyArray<string>;
  readAsDirectory?: (directoryPath: string) => boolean;
}

interface AliasOption {
  alias: string;
  name: string;
  onlyModule?: boolean;
}

resolve: {
  extensions: ['.ts', '.tsx', '.js', '.jsx', '.json', '.vue'],
}

// ❌ 错误：空字符串会导致额外一次 stat 调用
extensions: ['', '.js', '.ts']

// ✅ 正确
extensions: ['.ts', '.tsx', '.js', '.json']

resolve: {
  alias: {
    // 基础别名
    '@': path.resolve(__dirname, 'src/'),
    '@components': path.resolve(__dirname, 'src/components/'),

    // $ 结尾表示精确匹配（不会匹配 @vue/router）
    'vue$': 'vue/dist/vue.runtime.esm-bundler.js',

    // 设置为 false 可以阻止解析
    'ignored-module': false,

    // 数组形式：按顺序尝试
    'react': [
      'preact/compat/',       // 优先使用 Preact compat
      'react',                // 回退到 React
    ],
  },
}

// 配置: 'vue$': 'vue/dist/vue.esm-bundler.js'

import Vue from 'vue';            // ✅ 匹配 vue$，使用 esm-bundler 版本
import VueRouter from 'vue-router'; // ❌ 不匹配 vue$，走正常 node_modules 解析

resolve: {
  modules: [
    'node_modules',           // 项目本地
    path.resolve(__dirname, 'src/libs'),  // 自定义库目录
    path.resolve(__dirname, '../shared'), // Monorepo 共享目录
  ],
}

resolve: {
  // 自定义优先级：先找 browser，再找 es2015，最后 main
  mainFields: ['browser', 'es2015', 'module', 'main'],
}

{
  "name": "some-package",
  "main": "dist/cjs/index.js",
  "module": "dist/esm/index.mjs",
  "browser": "dist/browser/index.js",
  "es2015": "dist/es2015/index.js"
}

{
  "name": "my-package",
  "exports": {
    ".": {
      "import": "./dist/esm/index.mjs",
      "require": "./dist/cjs/index.cjs",
      "default": "./dist/cjs/index.cjs"
    },
    "./subpath": {
      "import": "./dist/esm/subpath.mjs",
      "require": "./dist/cjs/subpath.cjs"
    },
    "./package.json": "./package.json"
  }
}

// import 语句 → 匹配 "import" 条件
import foo from 'my-package';         // → ./dist/esm/index.mjs

// require 语句 → 匹配 "require" 条件
const bar = require('my-package');    // → ./dist/cjs/index.cjs

// 子路径导入
import sub from 'my-package/subpath'; // → ./dist/esm/subpath.mjs

resolve: {
  conditionNames: ['webpack', 'production', 'browser'],
}

resolve: {
  byDependency: {
    // 普通 ES Module 导入
    esm: {
      mainFields: ['browser', 'module', 'main'],
      extensions: ['.mjs', '.js', '.ts'],
    },

    // CommonJS require
    commonjs: {
      mainFields: ['main'],
      extensions: ['.js', '.cjs', '.json'],
    },

    // URL() 引用（CSS 中的 url()）
    url: {
      preferRelative: true,
    },

    // Web Worker
    worker: {
      mainFields: ['worker', 'module', 'main'],
    },

    // TypeScript（需配合 tsconfig）
    typescript: [],
  },
}

resolve: {
  fallback: {
    // 使用 npm 包替代
    "buffer": require.resolve("buffer/"),
    "crypto": require.resolve("crypto-browserify"),
    "stream": require.resolve("stream-browserify"),
    "util": require.resolve("util/"),
    "assert": require.resolve("assert/"),
    "http": require.resolve("stream-http"),
    "https": require.resolve("https-browserify"),
    "os": require.resolve("os-browserify/browser"),
    "url": require.resolve("url/"),
    "zlib": require.resolve("browserify-zlib"),

    // 设为 false 表示不提供 polyfill（报错提醒开发者）
    "fs": false,
    "path": false,
    "child_process": false,

    // 使用自定义实现
    "process": require.resolve("process/browser"),
  },
}

resolve: {
  tsconfig: {
    configFile: path.resolve(__dirname, 'tsconfig.build.json'),
    extensions: ['.ts', '.tsx'],
    // 只将这些包视为隐式依赖
    onlyImplicitDependenciesFor: ['@scope/package-name'],
  },
}

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@utils/*": ["src/utils/*"],
      "@components/*": ["src/components/*"]
    }
  }
}

// webpack.config.js — 自动读取 tsconfig paths 作为 alias
resolve: {
  extensions: ['.ts', '.tsx', '.js'],
  // tsconfig 会自动读取，无需手动配置 alias！
}

module.exports = {
  resolveLoader: {
    modules: ['node_modules', 'path/to/loaders'],  // Loader 搜索目录
    extensions: ['.js', '.json'],                   // Loader 文件扩展名
    mainFields: ['loader', 'main'],                 // package.json 字段
  },
};

const path = require('path');

module.exports = {
  resolve: {
    // === 扩展名（高频在前）===
    extensions: ['.ts', '.tsx', '.js', '.jsx', '.json', '.vue'],

    // === 别名 ===
    alias: {
      '@': path.resolve(__dirname, 'src/'),
      '@components': path.resolve(__dirname, 'src/components/'),
      '@utils': path.resolve(__dirname, 'src/utils/'),
      '@hooks': path.resolve(__dirname, 'src/hooks/'),
      '@assets': path.resolve(__dirname, 'src/assets/'),
      'vue$': 'vue/dist/vue.runtime.esm-bundler.js',
    },

    // === 搜索目录 ===
    modules: ['node_modules'],

    // === package.json 字段 ===
    mainFields: ['browser', 'module', 'main'],
    mainFiles: ['index'],

    // === Package Exports ===
    exportsFields: ['exports'],
    importsFields: ['imports'],
    conditionNames: ['webpack', process.env.NODE_ENV | | 'development', 'browser'],

    // === 差异化解析 ===
    byDependency: {
      esm: {
        mainFields: ['browser', 'module', 'main'],
      },
      commonjs: {
        mainFields: ['main'],
      },
      url: {
        preferRelative: true,
      },
    },

    // === Node.js Polyfill ===
    fallback: {
      "buffer": false,
      "crypto": false,
      "stream": false,
      "fs": false,
      "path": false,
    },

    // === TypeScript（v5.105+）===
    tsconfig: {
      configFile: path.resolve(__dirname, 'tsconfig.json'),
    },

    // === 性能优化 ===
    symlinks: false,
  },

  resolveLoader: {
    modules: ['node_modules'],
    extensions: ['.js'],
  },
};

interface Module {
  // === 核心规则 ===
  rules?: RuleSetRule[];

  // === 不解析的模块 ===
  noParse?: RegExp | RegExp[] | ((resource: string) => boolean);

  // === 缓存控制 ===
  unsafeCache?: boolean | ((module: { resource: string }) => boolean);

  // === 解析器（Parser）配置 ===
  parser?: {
    javascript?: JavascriptParserOptions;
    asset?: AssetParserOptions;
    css?: CssParserOptions;             // 需 experiments.css
    javascript/auto?: JavascriptParserOptions;
  };

  // === 生成器（Generator）配置 ===
  generator?: {
    asset?: AssetGeneratorOptions;
    'asset/inline'?: AssetGeneratorOptions;
    'asset/resource'?: AssetGeneratorOptions;
    'asset/source'?: AssetGeneratorOptions;
    javascript?: JavascriptGeneratorOptions;
    // ...
  };

  // === 默认规则（v5 新增）===
  defaultRules?: RuleSetRule[];

  // === 未知上下文 ===
  unknownContextRequest?: string;
  unknownContextRecursive?: boolean;
  unknownContextRegExp?: RegExp;
  unknownContextCritical?: boolean;

  exprContextRequest?: string;
  exprContextRecursive?: boolean;
  exprContextRegExp?: RegExp;
  exprContextCritical?: boolean;

  wrappedContextRegExp?: RegExp;
  wrappedContextRecursive?: boolean;
  wrappedContextCritical?: boolean;
}

interface RuleSetRule {
  // === 条件匹配 ===
  test?: RegExp | string | ((resource: string) => boolean);
  include?: RegExp | string | string[];
  exclude?: RegExp | string | string[];
  and?: RuleSetRule[];
  or?: RuleSetRule[];
  not?: RuleSetRule[];
  resource?: Condition;
  resourceQuery?: Condition;
  issuer?: Condition;
  issuerLayer?: string | string[];
  oneOf?: RuleSetRule[];

  // === 处理方式 ===
  use?: RuleSetUseItem | RuleSetUseItem[];
  loader?: string;
  options?: object;
  query?: object;  // 已废弃，使用 options

  // === 资源模块类型（v5 内置）===
  type?: 'asset' | 'asset/source' | 'asset/resource' | 'asset/inline'
       | 'javascript/auto' | 'javascript/esm' | 'json';

  // === 解析器细粒度控制 ===
  parser?: {
    javascript?: JavascriptParserOptions;
    dataUrlCondition?: DataUrlCondition;
  };

  // === 生成器配置 ===
  generator?: {
    filename?: string;
    publicPath?: string;
    emit?: boolean;
    outputPath?: string;
  };

  // === 副作用标记 ===
  sideEffects?: boolean | string[];

  // === 解析器选择 ===
  resolve?: ResolveOptions;

  // === Layer（v5.20+）===
  layer?: string;

  // === 编码 ===
  encoding?: boolean;

  // === 生成器类型 ===
  generator?: GeneratorOptions;

  // === mimetype ===
  mimetype?: string;
}

module: {
  rules: [
    // === test: 正则匹配文件路径 ===
    {
      test: /\.tsx?$/,           // 匹配 .ts/.tsx 文件
      use: 'ts-loader',
    },

    // === include: 白名单（仅匹配 src 目录）===
    {
      test: /\.js$/,
      include: path.resolve(__dirname, 'src'),
      use: 'babel-loader',
    },

    // === exclude: 黑名单（排除 node_modules）===
    {
      test: /\.js$/,
      exclude: /node_modules/,
      use: 'babel-loader',
    },

    // === 组合条件: and/or/not ===
    {
      test: /\.css$/,
      and: [
        { include: path.resolve(__dirname, 'src') },
        { not: [/node_modules/] },
      ],
      use: ['style-loader', 'css-loader'],
    },

    // === resourceQuery: 匹配查询字符串 ===
    {
      test: /\.png$/,
      resourceQuery: /inline/,   // 匹配 ?inline
      type: 'asset/inline',       // 内联为 base64
    },
    {
      test: /\.png$/,
      resourceQuery: /external/,  // 匹配 ?external
      type: 'asset/resource',     // 输出为独立文件
    },

    // === oneOf: 只应用第一个匹配的规则 ===
    {
      test: /\.(png|jpe?g|gif)$/i,
      oneOf: [
        {
          type: 'asset',
          parser: {
            dataUrlCondition: {
              maxSize: 8 * 1024,  // < 8KB 内联
            },
          },
        },
      ],
    },

    // === issuer: 匹配引用者 ===
    {
      test: /\.css$/,
      issuer: { and: [/\.html$/i] },  // 只有 .html 引用的 .css 才匹配
      use: ['style-loader', 'css-loader'],
    },
  ],
}

module: {
  rules: [
    {
      test: /\.less$/i,
      // use 数组：从右到左、从下到上执行
      use: [
        // === 第 1 个执行（最右边）===
        {
          loader: 'less-loader',        // Less → CSS
          options: {
            lessOptions: {
              strictMath: true,
            },
            sourceMap: isDev,
          },
        },

        // === 第 2 个执行 ===
        {
          loader: 'postcss-loader',      // CSS → 转换后的 CSS
          options: {
            postcssOptions: {
              plugins: [
                'autoprefixer',
                ...(isDev ? [] : ['cssnano']),
              ],
            },
          },
        },

        // === 第 3 个执行（最左边）===
        {
          loader: 'css-loader',          // CSS → JS 模块
          options: {
            importLoaders: 2,             // 前面有 2 个 loader
            modules: {
              localIdentName: isDev
                ? '[local]_[hash:base64:5]'
                : '[hash:base64:8]',
              exportLocalsConvention: 'camelCaseOnly',
            },
            sourceMap: isDev,
          },
        },

        // === 第 4 个执行（最终）===
        {
          loader: 'style-loader',        // JS → 注入 <style> 标签
          options: {
            injectType: 'singletonStyleTag',
            insert: 'head',
          },
        },
      ],
    },
  ],
}

Less 源码 → [less-loader] → CSS → [postcss-loader] → 转换后 CSS
→ [css-loader] → JS 模块 → [style-loader] → 注入 DOM

module: {
  rules: [
    // 图片：智能选择（< 8KB 内联，否则输出文件）
    {
      test: /\.(png|jpe?g|gif|svg|webp)$/i,
      type: 'asset',
      parser: {
        dataUrlCondition: {
          maxSize: 8 * 1024,  // 8KB
        },
      },
      generator: {
        filename: 'images/[name].[hash:8][ext]',
        publicPath: 'https://cdn.example.com/',
      },
    },

    // 字体：始终输出为文件
    {
      test: /\.(woff2?|eot|ttf|otf)$/i,
      type: 'asset/resource',
      generator: {
        filename: 'fonts/[name].[hash:8][ext]',
      },
    },

    // 文本：内联为字符串
    {
      test: /\.txt$/i,
      type: 'asset/source',
    },
  ],
}

module: {
  noParse: /jquery|lodash|angular/,
  // 或
  noParse: (content) => {
    return /jquery|lodash/.test(content);
  },
}

module: {
  // 全局开启
  unsafeCache: true,

  // 有条件地开启
  unsafeCache: (module) => {
    return /node_modules/.test(module.resource);
  },
}

interface JavascriptParserOptions {
  // === 动态导入 ===
  dynamicImportMode?: 'lazy' | 'lazy-once' | 'eager' | 'weak';
  dynamicImportPrefetch?: number | boolean;
  dynamicImportPreload?: number | boolean;

  // === import 表达式 ===
  importExpression?: boolean;
  importMeta?: boolean;
  importMetaContext?: boolean;

  // === 匿名默认导出名（v5.107 新增 ⭐）===
  anonymousDefaultExportName?: string | false;

  // === require ===
  requireEnsure?: boolean;
  requireContext?: boolean;
  requireInclude?: boolean;
  requireResolve?: boolean;

  // === 语法支持 ===
  url?: boolean;                  // new URL()
  worker?: [WorkerOptions];      // new Worker()

  // === 其他 ===
  javascript?: boolean;
  exportsPresence?: 'error' | 'warn' | 'auto';
  unknownContextRequest?: string;
  unknownContextRecursive?: boolean;
  unknownContextRegExp?: boolean;
  unknownContextCritical?: boolean;
  exprContextRequest?: string;
  exprContextRecursive?: boolean;
  exprContextRegExp?: boolean;
  exprContextCritical?: boolean;
  wrappedContextRegExp?: RegExp;
  wrappedContextRecursive?: boolean;
  wrappedContextCritical?: boolean;
  system?: boolean;
  // ...
}

module: {
  rules: [{
    test: /\.m?js$/,
    parser: {
      anonymousDefaultExportName: '__WEBPACK_DEFAULT_EXPORT__',
      // 或设为 false 禁用此功能
      // anonymousDefaultExportName: false,
    },
  }],
}

module.exports = {
  module: {
    // === 加载规则 ===
    rules: [
      // TypeScript
      {
        test: /\.tsx?$/,
        use: [{
          loader: 'ts-loader',
          options: { transpileOnly: true },
        }],
        exclude: /node_modules/,
      },

      // Vue SFC
      {
        test: /\.vue$/,
        use: 'vue-loader',
      },

      // CSS/Less/Sass
      {
        test: /\.css$/i,
        oneOf: [
          {
            resourceQuery: /module/,     // CSS Modules
            use: [
              'style-loader',
              {
                loader: 'css-loader',
                options: {
                  modules: {
                    localIdentName: '[local]_[hash:base64:5]',
                    exportLocalsConvention: 'camelCaseOnly',
                  },
                  importLoaders: 1,
                  sourceMap: isDev,
                },
              },
              'postcss-loader',
            ],
          },
          {
            use: [
              'style-loader',
              {
                loader: 'css-loader',
                options: {
                  importLoaders: 1,
                  sourceMap: isDev,
                },
              },
              'postcss-loader',
            ],
          },
        ],
      },

      // 图片资源
      {
        test: /\.(png|jpe?g|gif|svg|webp|avif)$/i,
        type: 'asset',
        parser: {
          dataUrlCondition: {
            maxSize: 8 * 1024,
          },
        },
        generator: {
          filename: 'images/[name].[hash:8][ext]',
        },
      },

      // 字体资源
      {
        test: /\.(woff2?|eot|ttf|otf)$/i,
        type: 'asset/resource',
        generator: {
          filename: 'fonts/[name].[hash:8][ext]',
        },
      },
    ],

    // === 不解析的大型库 ===
    noParse: /jquery|lodash-es|chart\.js/,

    // === 解析器配置 ===
    parser: {
      javascript: {
        dynamicImportMode: 'lazy',
        anonymousDefaultExportName: '__default',
        importMeta: true,
        url: true,
      },
      asset: {
        dataUrlCondition: {
          maxSize: 8 * 1024,
        },
      },
    },
  },
};

interface Optimization {
  // === 代码分割 ===
  splitChunks?: SplitChunksOptions | false;
  runtimeChunk?: boolean | string | RuntimeChunkConfig;

  // === 压缩 ===
  minimize?: boolean;
  minimizer?: ('...' | TerserPlugin | CssMinimizerPlugin | SwcMinimizerPlugin)[];

  // === Tree Shaking & Scope Hoisting ===
  usedExports?: boolean;
  sideEffects?: boolean;
  concatenateModules?: boolean;
  innerGraph?: boolean;

  // === ID 策略 ===
  moduleIds?: 'natural' | 'named' | 'deterministic' | 'size' | 'hashed';
  chunkIds?: 'natural' | 'named' | 'deterministic' | 'size' | 'hashed';
  mangleWasmImports?: boolean;

  // === Hash 策略 ===
  realContentHash?: boolean;
  hashFunction?: Algorithm;
  hashDigest?: string;
  hashDigestLength?: number;
  hashSalt?: string;

  // === Chunk 优化 ===
  removeAvailableModules?: boolean;
  removeEmptyChunks?: boolean;
  mergeDuplicateChunks?: boolean;
  flagIncludedChunks?: boolean;
  portableRecords?: Record<string, any>;

  // === 环境变量 ===
  nodeEnv?: string | false;

  // === 其他 ===
  checkWasmTypes?: boolean;
  mangleWasmImports?: boolean;
  emitOnErrors?: boolean;
  moduleIds?: 'natural' | 'named' | 'deterministic' | 'size';
  chunkIds?: 'natural' | 'named' | 'deterministic' | 'size';
  providedExports?: boolean;
  chunkLoading?: boolean;
  record?: string;
  recordsInputPath?: string;
  recordsOutputPath?: string;
}

// concatenateModules: false（传统模式）
(function(module, exports, __webpack_require__) {
  // 模块 A
  module.exports = function add(a, b) { return a + b; };
})(/* module id */);

(function(module, exports, __webpack_require__) {
  // 模块 B
  var add = __webpack_require__(/* module A */);
  module.exports = function mul(a, b) { return a * 2 + add(a, b); };
})(/* module id */);

// concatenateModules: true（Scope Hoisting）
(function(module, exports, __webpack_require__) {
  // 所有模块合并到一个函数作用域
  function add(a, b) { return a + b; }
  function mul(a, b) { return a * 2 + add(a, b); }
  module.exports = mul;
})(/* module id */);

// utils.js
export function usedFunc() { return 42; }
export function unusedFunc() { return 'dead code'; }

// index.js
import { usedFunc } from './utils';
console.log(usedFunc());

// usedExports: true 时，unusedFunc 会在压缩阶段被移除

package.json: { "sideEffects": false }
        ↓
Webpack 发现某个模块的所有导出都未被使用
        ↓
sideEffects: true → 安全移除整个模块（包括其副作用代码）
sideEffects: false → 即使导出未被使用，也保留模块（可能有副作用）

const TerserPlugin = require('terser-webpack-plugin');
const CssMinimizerPlugin = require('css-minimizer-webpack-plugin');

optimization: {
  minimize: true,
  minimizer: [
    // === JavaScript 压缩 ===
    new TerserPlugin({
      // 并行压缩
      parallel: true,
      // 提取注释到 .LICENSE 文件
      extractComments: false,
      // 排除某些文件
      exclude: /node_modules[/\\]some-lib/,
      // Terser 选项
      terserOptions: {
        compress: {
          drop_console: isProduction,        // 移除 console
          drop_debugger: isProduction,        // 移除 debugger
          pure_funcs: isProduction ? ['console.info', 'console.debug'] : [],  // 移除特定函数调用
          passes: 2,                          // 多轮压缩
          ecma: 2020,                         // 目标 ES 版本
          warnings: false,
          arrows: true,                       // class 中的箭头函数
          collapse_vars: true,                // 折叠单定义变量
          comparisons: true,                  // 优化比较表达式
          computed_props: true,               // 计算属性常量化
          hoist_funs: true,                   // 提升 function 声明
          hoist_props: true,                  // 提升属性
          reduce_vars: true,                  // 减少变量
          switches: true,                     // 优化 switch
          typeofs: true,                      // 优化 typeof
        },
        format: {
          comments: /^!|@preserve|@lic|@cc_on/i,  // 保留特定注释
          beautify: false,                        // 不美化
          ecma: 2020,
          wrap_func_args: true,                   // 包装函数参数
        },
        mangle: {
          safari10: true,                    // Safari 10 兼容
          reserved: ['$', 'exports', 'require', 'module'],  // 保留名称
        },
      },
      // 使用 SWC 替代 Terser（更快）
      // minify: TerserPlugin.swcMinify,
    }),

    // === CSS 压缩 ===
    new CssMinimizerPlugin({
      parallel: true,
      minimizerOptions: {
        preset: [
          'default',
          {
            discardComments: { removeAll: true },
            normalizeWhitespace: false,
          },
        ],
      },
    }),
  ],
}

// 使用 SWC 替代 Terser（快 20-70 倍）
new TerserPlugin({
  minify: TerserPlugin.swcMinify,
  terserOptions: {
    compress: true,
    mangle: true,
  },
})

interface SplitChunksOptions {
  chunks?: 'initial' | 'async' | 'all' | (string: string) => boolean;
  minSize?: number | { min?: number; max?: number };
  minRemainingSize?: number;
  minChunks?: number;
  maxAsyncRequests?: number;
  maxInitialRequests?: number;
  hidePathInfo?: boolean;
  automaticNameDelimiter?: string;
  automaticNameMaxLength?: number;
  maxSize?: number | { max?: number; min?: number; hint?: string };
  enforceSizeThreshold?: number;
  cacheGroups?: false | Record<string, CacheGroupOptions>;
  filename?: string | ((pathData: PathData) => string);
  name?: boolean | string | ((module: Module, chunks: Chunk[], cacheGroupKey: string) => string);
}

interface CacheGroupOptions {
  test?: ((module: Module, { name: string, type: string }) => boolean) | string | RegExp;
  priority?: number;
  reuseExistingChunk?: boolean;
  minSize?: number | { min?: number; max?: number };
  minChunks?: number;
  maxAsyncRequests?: number;
  maxInitialRequests?: number;
  maxSize?: number | { max?: number; min?: size; hint?: string };
  filename?: string | ((pathData: PathData) => string);
  idHint?: string;
  name?: boolean | string | ((module: Module, chunks: Chunk[], cacheGroupKey: string) => string);
  enforce?: boolean;
  type?: string;
}

optimization: {
  splitChunks: {
    // === 分割范围 ===
    chunks: 'all',  // 包括同步和异步模块

    // === 最小尺寸阈值 ===
    minSize: 20000,              // 20KB
    minRemainingSize: 0,
    maxSize: 244000,             // 244KB（超出则继续分割）
    minChunks: 1,                // 至少被 1 个 chunk 引用

    // === 最大请求数 ===
    maxAsyncRequests: 30,        // 异步 chunk 最大并行数
    maxInitialRequests: 30,      // 入口点最大并行数
    enforceSizeThreshold: 50000, // >50KB 强制分割

    // === 缓存分组 ===
    cacheGroups: {
      // === Framework: React/Vue/Angular 核心 ===
      framework: {
        test: /[\\/]node_modules[\\/](react|react-dom|react-router|@vue|vue|next|angular)/,
        name: 'framework',
        priority: 40,
        chunks: 'all',
        enforce: true,
      },

      // === Vendor: 其他第三方库 ===
      vendor: {
        test: /[\\/]node_modules[\\/]/,
        name: 'vendor',
        priority: 20,
        chunks: 'all',
        reuseExistingChunk: true,
        minChunks: 1,
      },

      // === Common: 公共业务代码 ===
      common: {
        name: 'common',
        minChunks: 2,            // 至少被 2 个 chunk 共享
        priority: 10,
        chunks: 'initial',
        reuseExistingChunk: true,
      },

      // === Utilities: 工具库（lodash 等）===
      utilities: {
        test: /[\\/]node_modules[\\/](lodash|axios|dayjs)/,
        name: 'utilities',
        priority: 25,
        chunks: 'all',
        reuseExistingChunk: true,
      },
    },
  },
}

runtimeChunk: {
  name: (entrypoint) => `runtime-${entrypoint.name}`,
}

// 或简化形式
runtimeChunk: 'single',  // 所有入口共享一个 runtime
// runtimeChunk: true,    // 等价于 'single'
// runtimeChunk: 'multiple', // 每个入口一个 runtime

不提取:
  main.a1b2c3.js    (业务代码 + 运行时) → 内容变化 → hash 变化
  vendor.e5f6g7.js   (第三方库)           → 内容不变 → hash 不变

提取后:
  main.a1b2c3.js    (业务代码)           → 内容变化 → hash 变化
  vendor.e5f6g7.js   (第三方库)           → 内容不变 → hash 不变
  runtime.h1i2j3.js  (运行时代码)         → 通常不变 → 长期缓存 ✅

optimization: {
  moduleIds: 'deterministic',  // v5.107 production 默认值
  chunkIds: 'deterministic',   // v5.107 production 默认值
}

optimization: {
  portableRecords: true,
  realContentHash: true,
}

const TerserPlugin = require('terser-webpack-plugin');
const CssMinimizerPlugin = require('css-minimizer-webpack-plugin');

module.exports = {
  optimization: {
    // === Scope Hoisting ===
    concatenateModules: true,

    // === Tree Shaking ===
    usedExports: true,
    sideEffects: true,
    innerGraph: true,

    // === 压缩 ===
    minimize: !isDev,
    minimizer: isDev ? [] : [
      new TerserPlugin({
        parallel: true,
        extractComments: false,
        terserOptions: {
          compress: {
            drop_console: true,
            drop_debugger: true,
            pure_funcs: ['console.info', 'console.debug'],
            passes: 2,
            ecma: 2020,
          },
          format: {
            comments: false,
            ecma: 2020,
          },
          mangle: {
            safari10: true,
          },
        },
      }),
      new CssMinimizerPlugin(),
    ],

    // === 代码分割 ===
    runtimeChunk: 'single',
    splitChunks: {
      chunks: 'all',
      minSize: 20000,
      maxSize: 244000,
      minChunks: 1,
      cacheGroups: {
        framework: {
          test: /[\\/]node_modules[\\/](react|react-dom|react-router|@vue|vue)/,
          name: 'framework',
          priority: 40,
          chunks: 'all',
          enforce: true,
        },
        vendor: {
          test: /[\\/]node_modules[\\/]/,
          name: 'vendor',
          priority: 20,
          chunks: 'all',
          reuseExistingChunk: true,
        },
        common: {
          name: 'common',
          minChunks: 2,
          priority: 10,
          chunks: 'initial',
          reuseExistingChunk: true,
        },
      },
    },

    // === ID 策略 ===
    moduleIds: 'deterministic',
    chunkIds: 'deterministic',
    realContentHash: true,

    // === 其他 ===
    removeEmptyChunks: true,
    mergeDuplicateChunks: true,
    flagIncludedChunks: true,
    portableRecords: isCI,
  },
};

type DevTool =
  | false
  | 'eval'
  | 'eval-cheap-source-map'
  | 'eval-cheap-module-source-map'
  | 'eval-source-map'
  | 'eval-nosources-source-map'
  | 'cheap-source-map'
  | 'cheap-module-source-map'
  | 'inline-cheap-source-map'
  | 'inline-cheap-module-source-map'
  | 'inline-source-map'
  | 'nosources-source-map'
  | 'hidden-source-map'
  | 'source-map'
  | string;  // 自定义模板
  | Array<string | false>;  // v5.105+ 新增 ⭐

module.exports = {
  devtool: [
    // JavaScript: 完整独立的 sourcemap
    'source-map',
    // CSS: 内联 sourcemap（CSS 通常较小）
    'inline-source-map?onlyCSSModuleSourceMap',
  ],
}

[inline-|hidden-|nosources-][cheap-[-module-]]source-map
 | |           | |
 | |           |           └── 基础格式
 | |           └── 是否包含列信息（cheap = 无列）
 |           └── 特殊模式
 └── 内联方式（DataURL）

module.exports = {
  // === 开发环境 ===
  // 推荐方案：速度快 + 能看到原始源码（无列信息）
  devtool: isDev ? 'eval-cheap-module-source-map' : false,

  // === 生产环境 ===
  // 方案 A：标准 sourcemap（可上传到 Sentry 等服务）
  // devtool: 'source-map',

  // 方案 B：隐藏 sourcemap（生成但不暴露给用户）
  // devtool: 'hidden-source-map',

  // 方案 C：无源码 sourcemap（只有堆栈信息，无源码）
  // devtool: 'nosources-source-map',

  // 方案 D：不生成（最小体积）
  // devtool: false,
}

type Target =
  | false
  | string                              // 如 'web', 'node14', 'electron-main'
  | string[]                            // 如 ['web', 'es2020']
  | ((compiler: Compiler) => false | string | string[]);

// 使用 browserslist 配置
target: 'browserslist',

// 或带自定义查询
target: 'browserslist:last 2 versions, not dead, not ie 11',

// 组合多个目标
target: ['web', 'es2020'],

// 函数形式（动态决定）
target: (compiler) => {
  if (process.env.BUILD_TARGET === 'node') {
    return 'node18';
  }
  return ['web', 'es2020'];
},

// 禁用目标设定
target: false,  // 不注入任何平台特定的代码

// src/index.js
import('./module').then(console.log);

// 注入了 JSONP 异步加载运行时
var jsonpArray = window["webpackJsonp"] = window["webpackJsonp"] | | [];
// ... 大量 JSONP 相关运行时
__webpack_require__.e = function(chunkId) {
  // 创建 script 标签加载异步 chunk
  var script = document.createElement('script');
  script.src = __webpack_require__.p + "" + ({}[chunkId]| |chunkId) + "." + hash + ".hot-update.js";
  // ...
}

// 直接使用 Node.js require，无需 JSONP
__webpack_require__.e = function(chunkId) {
  return Promise.resolve().then(function() {
    __webpack_require__(m = chunkId);
  });
}
// 显著更简洁

module.exports = {
  // === Web 应用（最常见）===
  target: 'browserslist',

  // === Node.js 应用 ===
  // target: 'node18',

  // === Electron 应用 ===
  // target: ['web', 'electron-renderer'],

  // === Library（通用）===
  // target: ['web', 'es2020'],

  // === Service Worker ===
  // target: 'webworker',
}

interface Validate {
  strict?: boolean;
  rules?: Record<string, ValidateRule>;
}

type ValidateRule =
  | ((value: any, context: ValidationContext) => void)
  | {
      validator: (value: any, context: ValidationContext) => void;
      message?: string;
    };

module.exports = {
  validate: {
    // 严格模式：遇到未知配置项时报错
    strict: true,

    // 自定义验证规则
    rules: {
      // 验证 output.path 存在
      'output.path': (value) => {
        if (!value | | typeof value !== 'string') {
          throw new Error('output.path must be a non-empty string');
        }
        if (!path.isAbsolute(value)) {
          throw new Error(`output.path must be an absolute path, got: ${value}`);
        }
      },

      // 验证 mode 合法性
      'mode': (value) => {
        const validModes = ['development', 'production', 'none'];
        if (!validModes.includes(value)) {
          throw new Error(`mode must be one of ${validModes.join(', ')}, got: ${value}`);
        }
      },

      // 验证 entry 不为空
      'entry': (value) => {
        if (!value | | (typeof value === 'object' && Object.keys(value).length === 0)) {
          throw new Error('entry cannot be empty');
        }
      },

      // 验证 optimization.splitChunks 配置
      'optimization.splitChunks.chunks': (value) => {
        const validChunks = ['initial', 'async', 'all'];
        if (!validChunks.includes(value)) {
          throw new Error(`splitChunks.chunks must be ${validChunks.join(' or ')}`);
        }
      },
    },
  },
};

const { validate } = require('schema-utils');
const schema = require('./webpack.schema.json');

module.exports = {
  validate: {
    strict: true,
    rules: {
      // 使用 schema-utils 进行深度验证
      '*': (value, context) => {
        validate(schema, value, {
          name: 'Webpack Config',
          baseDataPath: 'config',
        });
      },

      // 条件验证
      'output.library': (value) => {
        if (value && value.type === 'module') {
          if (!this.experiments?.outputModule) {
            throw new Error(
              'output.library.type "module" requires experiments.outputModule to be enabled'
            );
          }
        }
      },

      // 跨字段关联验证
      'optimization.minimize': (value) => {
        if (value && !this.optimization?.minimizer?.length) {
          console.warn(
            'optimization.minimize is true but no minimizers configured. Using defaults.'
          );
        }
      },
    },
  },
};

interface Experiments {
  css?: boolean | CssExperimentOptions;
  html?: boolean;
  typescript?: boolean;
  futureDefaults?: boolean;
  lazyCompilation?: LazyCompilationOptions;
  buildHttp?: BuildHttpOptions;
  cacheUnaffected?: boolean;
  outputModule?: boolean;
  syncWebAssembly?: boolean;
  asyncWebAssembly?: boolean;
  topLevelAwait?: boolean;
  layers?: boolean;
  incrementalRebuild?: boolean;
  sourceImport?: boolean;           // v5.106+
  deferImport?: boolean;
  allowOptionalOutdated?: boolean;
  buildHttp?: BuildHttpOptions;
  backCompat?: boolean;
}

experiments: {
  lazyCompilation: {
    entries: false,          // 不懒编译入口文件
    imports: true,           // 懒编译动态 import()
    tests: /\.lazy\.js$/,   // 匹配特定模式的模块
  },
}

用户访问 /dashboard
    ↓
Webpack 收到请求
    ↓
按需编译 dashboard 及其依赖
    ↓
返回编译后的代码（首次较慢，后续命中缓存）

experiments: {
  buildHttp: {
    allowedUris: [
      /^https:\/\/cdn\.example\.com/,  // 允许的 CDN 域名
      /^https:\/\/unpkg\.com/,          // 允许 unpkg
    ],
    cacheLocation: path.resolve(__dirname, '.http-cache'),  // 缓存目录
    frozen: isCI,        // CI 环境锁定缓存
    lockfile: path.resolve(__dirname, 'http-cache.lock'),   // 锁文件
    upgrade: false,      // 不自动升级过期缓存
  },
}

// 直接从 CDN 导入
import React from 'https://cdn.example.com/react@18.2.0.esm.js';
import _ from 'https://cdn.example.com/lodash-es@4.17.21.esm.js';

experiments: {
  sourceImport: true,
}

// 传统方式（查询字符串）
import logoUrl from './logo.png?url';
import svgRaw from './icon.svg?raw';

// sourceImport 方式（更语义化）
import logoUrl from source './logo.png';     // 等价于 ?url
import svgRaw from source './icon.svg';       // 等价于 ?raw

// webpack.config.js
const path = require('path');
const TerserPlugin = require('terser-webpack-plugin');
const CssMinimizerPlugin = require('css-minimizer-webpack-plugin');
const pkg = require('./package.json');

const isDev = process.env.NODE_ENV !== 'production';
const isCI = !!process.env.CI;
const enableESM = process.env.ESM_OUTPUT === 'true';

module.exports = {
  // ============================================================
  // 模式
  // ============================================================
  mode: isDev ? 'development' : 'production',

  // ============================================================
  // 目标环境
  // ============================================================
  target: 'browserslist',

  // ============================================================
  // 入口
  // ============================================================
  entry: {
    main: {
      import: ['./src/polyfills.ts', './src/main.tsx'],
      filename: 'js/app.[contenthash:8].js',
    },
    admin: {
      import: './src/admin.tsx',
      filename: 'js/admin.[contenthash:8].js',
      dependOn: 'main',
    },
  },

  // ============================================================
  // 输出
  // ============================================================
  output: {
    path: path.resolve(__dirname, 'dist'),
    publicPath: '/',
    filename: isDev ? 'js/[name].js' : 'js/[name].[contenthash:8].js',
    chunkFilename: isDev ? 'js/[name].chunk.js' : 'js/[name].[contenthash:8].chunk.js',
    assetModuleFilename: 'assets/[name].[hash:8][ext]',

    // v5.107: ESM 输出
    module: enableESM,

    // 清理
    clean: isDev ? false : {
      keep: /\/assets/,
    },

    // 目标环境
    environment: {
      arrowFunction: false,
      const: false,
      destructuring: false,
      bigIntLiteral: false,
      optionalChaining: true,
      nullishCoalescingOperator: true,
    },

    // 性能
    compareBeforeEmit: !isDev,

    // Chunk 配置
    chunkFormat: 'array-push',
    chunkLoading: 'jsonp',
    charset: true,
    crossOriginLoading: 'anonymous',
    uniqueName: 'my-app-v1',
  },

  // ============================================================
  // 模块解析
  // ============================================================
  resolve: {
    extensions: ['.ts', '.tsx', '.js', '.jsx', '.json', '.vue'],
    alias: {
      '@': path.resolve(__dirname, 'src'),
      'vue$': 'vue/dist/vue.runtime.esm-bundler.js',
    },
    modules: ['node_modules'],
    mainFields: ['browser', 'module', 'main'],
    exportsFields: ['imports'],
    conditionNames: ['webpack', isDev ? 'development' : 'production', 'browser'],
    byDependency: {
      esm: { mainFields: ['browser', 'module', 'main'] },
      commonjs: { mainFields: ['main'] },
      url: { preferRelative: true },
    },
    fallback: {
      buffer: false,
      crypto: false,
      stream: false,
      fs: false,
      path: false,
    },
    symlinks: false,
    tsconfig: path.resolve(__dirname, 'tsconfig.json'),
  },

  // ============================================================
  // 模块处理
  // ============================================================
  module: {
    rules: [
      // TypeScript
      {
        test: /\.tsx?$/,
        use: [{ loader: 'ts-loader', options: { transpileOnly: true } }],
        exclude: /node_modules/,
      },
      // Vue
      { test: /\.vue$/, use: 'vue-loader' },
      // CSS
      {
        test: /\.css$/i,
        oneOf: [
          {
            resourceQuery: /module/,
            use: ['style-loader', {
              loader: 'css-loader',
              options: {
                modules: { localIdentName: '[local]_[hash:base64:5]' },
                importLoaders: 1,
              },
            }, 'postcss-loader'],
          },
          { use: ['style-loader', 'css-loader', 'postcss-loader'] },
        ],
      },
      // 图片
      {
        test: /\.(png|jpe?g|gif|svg|webp)$/i,
        type: 'asset',
        parser: { dataUrlCondition: { maxSize: 8 * 1024 } },
        generator: { filename: 'images/[name].[hash:8][ext]' },
      },
      // 字体
      {
        test: /\.(woff2?|eot|ttf|otf)$/i,
        type: 'asset/resource',
        generator: { filename: 'fonts/[name].[hash:8][ext]' },
      },
    ],
    noParse: /lodash-es|chart\.js/,
    parser: {
      javascript: {
        dynamicImportMode: 'lazy',
        anonymousDefaultExportName: '__default',
      },
    },
  },

  // ============================================================
  // 优化
  // ============================================================
  optimization: {
    concatenateModules: true,
    usedExports: true,
    sideEffects: true,
    innerGraph: true,
    minimize: !isDev,
    minimizer: isDev ? [] : [
      new TerserPlugin({
        parallel: true,
        extractComments: false,
        terserOptions: {
          compress: {
            drop_console: true,
            drop_debugger: true,
            passes: 2,
            ecma: 2020,
          },
          format: { comments: false, ecma: 2020 },
          mangle: { safari10: true },
        },
      }),
      new CssMinimizerPlugin({ parallel: true }),
    ],
    runtimeChunk: 'single',
    splitChunks: {
      chunks: 'all',
      minSize: 20000,
      maxSize: 244000,
      cacheGroups: {
        framework: {
          test: /[\\/]node_modules[\\/](react|react-dom|react-router|@vue|vue)/,
          name: 'framework',
          priority: 40,
          enforce: true,
        },
        vendor: {
          test: /[\\/]node_modules[\\/]/,
          name: 'vendor',
          priority: 20,
          reuseExistingChunk: true,
        },
        common: {
          name: 'common',
          minChunks: 2,
          priority: 10,
          reuseExistingChunk: true,
        },
      },
    },
    moduleIds: 'deterministic',
    chunkIds: 'deterministic',
    realContentHash: true,
    removeEmptyChunks: true,
    mergeDuplicateChunks: true,
    flagIncludedChunks: true,
    portableRecords: isCI,
  },

  // ============================================================
  // Sourcemap
  // ============================================================
  devtool: isDev ? 'eval-cheap-module-source-map' : 'source-map',

  // ============================================================
  // 实验性功能
  // ============================================================
  experiments: {
    outputModule: enableESM,
    lazyCompilation: {
      entries: false,
      imports: true,
    },
    cacheUnaffected: true,
  },

  // ============================================================
  // 配置验证 (v5.106+)
  // ============================================================
  validate: {
    strict: true,
  },

  // ============================================================
  // 缓存
  // ============================================================
  cache: {
    type: 'filesystem',
    compression: 'gzip',
    maxAge: 1000 * 60 * 60 * 24 * 7,
    readonly: !isDev,
    profile: isDev,
    version: `${pkg.version}-v5.107`,
    buildDependencies: { config: [__filename] },
  },

  // ============================================================
  // 性能预算
  // ============================================================
  performance: {
    hints: isDev ? false : 'warning',
    maxEntrypointSize: 512000,
    maxAssetSize: 512000,
  },

  // ============================================================
  // 统计信息
  // ============================================================
  stats: isDev ? 'minimal' : 'normal',
};