配置文件语言

webpackjsorg-main配置参考

配置文件语言

Webpack 支持以多种编程语言和数据格式编写配置文件。您可以根据项目需求选择最合适的格式——无论是 JavaScript、TypeScript、CoffeeScript，还是像 JSON5、YAML 或 TOML 这样的纯数据文件。

defineConfig

defineConfig 是 webpack 导出的一個辅助函数，无需额外类型注解即可为您的配置提供编辑器的类型检查和自动补全。它本质上是一个标识函数（在运行时不做任何操作，直接返回传入的配置），因此它也适用于纯 JavaScript 配置文件。

webpack.config.js

js 复制代码

const { defineConfig } = require("webpack");

module.exports = defineConfig({
  mode: "none",
});

它可以接受 webpack-cli 能加载的任何形式：单个配置对象、配置数组（多编译器）、返回上述任一形式的函数、此类函数的数组，或者解析为上述任一形式的 Promise。

js 复制代码

const { defineConfig } = require("webpack");

module.exports = defineConfig((env, argv) => ({
  mode: argv.mode ?? "development",
  // ...
}));

TypeScript

要使用 TypeScript 编写 webpack 配置，首先需要安装必要的依赖，即 TypeScript 和来自 DefinitelyTyped 项目的相关类型定义：

bash 复制代码

npm install --save-dev typescript ts-node @types/node
# 如果使用 webpack-dev-server < v4.7.0，还需安装：
npm install --save-dev @types/webpack-dev-server

然后开始编写您的配置：

webpack.config.ts

ts 复制代码

import path from "node:path";
import { fileURLToPath } from "node:url";

import webpack from "webpack";
// 在配置 `devServer` 时如果遇到 TypeScript 类型错误，请引入此模块
import "webpack-dev-server";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

const config: webpack.Configuration = {
  mode: "production",
  entry: "./foo.js",
  output: {
    path: path.resolve(__dirname, "dist"),
    filename: "foo.bundle.js",
  },
};

export default config;

tsconfig.json

json 复制代码

{
  "compilerOptions": {
    "module": "esnext",
    "moduleResolution": "bundler",

    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "resolveJsonModule": true,
    "isolatedModules": true,

    // 允许编写 `import ... from './file.ts';`
    "rewriteRelativeImportExtensions": true
  }
}

上述示例假定您使用的是 TypeScript 2.7 或更高版本，并在 tsconfig.json 文件中启用了新的 esModuleInterop 和 allowSyntheticDefaultImports 编译器选项。

我们同时支持 CommonJS 和 ESM 格式的配置。

从 Node.js v22.18.0 开始，Node.js 内置了类型剥离（type stripping）功能，因此以下描述的额外设置仅对旧版本需要。

若要启用需要生成 JavaScript 代码的非可擦除 TypeScript 语法（如枚举声明、参数属性）的转换，请使用标记 --experimental-transform-types。

如果您使用的是不支持 typescript 格式的旧版 Node.js，或者希望在 tsconfig.json 中将 compilerOptions 中的 module 设置为 commonjs，则有三种解决方案：

修改 tsconfig.json。
修改 tsconfig.json 并为 ts-node 添加设置。
安装 tsconfig-paths。

方案一：打开您的 tsconfig.json 文件，找到 compilerOptions。将 target 设置为 "ES5"，并将 module 设置为 "CommonJS"（或者完全移除 module 选项）。

方案二：为 ts-node 添加设置：

您可以在 tsc 中保留 "module": "ESNext"，如果使用 webpack 或其他构建工具，可以为 ts-node 设置覆盖项。请参考 ts-node 配置

json 复制代码

{
  "compilerOptions": {
    "module": "ESNext"
  },
  "ts-node": {
    "compilerOptions": {
      "module": "CommonJS"
    }
  }
}

方案三：安装 tsconfig-paths 包：

bash 复制代码

npm install --save-dev tsconfig-paths

并专门为 webpack 配置创建一个单独的 TypeScript 配置文件：

tsconfig-for-webpack-config.json

json 复制代码

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "es5",
    "esModuleInterop": true
  }
}

T> ts-node 可以通过 tsconfig-paths 提供的环境变量解析 tsconfig.json 文件。

然后，像这样设置 tsconfig-paths 提供的环境变量 process.env.TS_NODE_PROJECT：

package.json

json 复制代码

{
  "scripts": {
    "build": "cross-env TS_NODE_PROJECT=\"tsconfig-for-webpack-config.json\" webpack"
  }
}

W> 我们收到报告称 TS_NODE_PROJECT 可能因 "TS_NODE_PROJECT" unrecognized command 错误而无法工作。因此，使用 cross-env 运行似乎可以解决此问题，更多信息请参见此问题。

CoffeeScript

同样，要使用 CoffeeScript，首先需要安装必要的依赖：

bash 复制代码

npm install --save-dev coffeescript

然后开始编写您的配置：

webpack.config.coffee

coffeescript 复制代码

import path from 'node:path'
import { fileURLToPath } from 'node:url'
import HtmlWebpackPlugin from 'html-webpack-plugin'
import webpack from 'webpack'

__filename = fileURLToPath(import.meta.url)
__dirname = path.dirname(__filename)

config =
  mode: 'production'
  entry: './path/to/my/entry/file.js'
  output:
    path: path.resolve(__dirname, 'dist')
    filename: 'my-first-webpack.bundle.js'
  module:
    rules: [
      {
        test: /\.(js|jsx)$/
        use: 'babel-loader'
      }
    ]
  plugins: [
    new HtmlWebpackPlugin(template: './src/index.html')
  ]

export default config

Babel 和 JSX

在下面的示例中，使用了 JSX（React JavaScript Markup）和 Babel 来创建 webpack 可以理解的 JSON 配置。

感谢 Jason Miller

首先，安装必要的依赖：

bash 复制代码

npm install --save-dev babel-register jsxobj babel-preset-es2015

.babelrc

json 复制代码

{
  "presets": ["es2015"]
}

webpack.config.babel.js

{/* eslint-skip */}

jsx 复制代码

import jsxobj from "jsxobj";

// 导入插件的示例
const CustomPlugin = (config) => ({
  ...config,
  name: "custom-plugin",
});

export default (
  <webpack target="web" watch mode="production">
    <entry path="src/index.js" />
    <resolve>
      <alias
        {...{
          react: "preact-compat",
          "react-dom": "preact-compat",
        }}
      />
    </resolve>
    <plugins>
      <CustomPlugin foo="bar" />
    </plugins>
  </webpack>
);

W> 如果您在其他地方使用了 Babel 且将 modules 设置为 false，则必须维护两个独立的 .babelrc 文件，或者使用 const jsxobj = require('jsxobj'); 和 module.exports 代替新的 import 和 export 语法。这是因为 Node 虽然支持许多新的 ES6 特性，但尚不支持 ES6 模块语法。

数据格式（JSON5、YAML 和 TOML）

当您的配置纯粹是静态数据——没有函数、没有 process.env 读取、没有计算值——您可以将它编写为数据文件而无需使用 JavaScript。webpack-cli 可直接解析以下扩展名：

扩展名	解析包
`.json5`	`json5`
`.yaml`, `.yml`	`js-yaml`
`.toml`	`toml`

解析器不随 webpack-cli 捆绑——需要根据您需要的格式安装对应的包作为开发依赖。如果缺失，webpack-cli 会停止运行并明确告诉您需要安装哪个包。

bash 复制代码

npm install --save-dev json5
# 或
npm install --save-dev js-yaml
# 或
npm install --save-dev toml

通过 --config 指向该文件，或者将其命名为默认配置以便自动加载（例如 webpack.config.json5）：

bash 复制代码

npx webpack --config webpack.config.toml

webpack.config.json5

json5 复制代码

{
  // JSON5 允许注释、不带引号的键和尾随逗号
  mode: "production",
  entry: "./src/index.js",
  output: {
    filename: "bundle.js",
  },
}

webpack.config.yaml

yaml 复制代码

mode: production
entry: ./src/index.js
output:
  filename: bundle.js

webpack.config.toml

toml 复制代码

mode = "production"
entry = "./src/index.js"

[output]
filename = "bundle.js"

T> 这些格式仅描述纯数据。当您需要动态配置——基于环境的分支、插件实例或函数形式——请改用 JavaScript 或 TypeScript 配置文件。

帮助我们改进文档

发现翻译问题或内容错误？请告诉我们。