Watch 配置

Webpack 可以监视文件，并在它们发生变化时重新编译。本页说明如何启用该功能，以及在监视功能无法正常工作时可以进行的若干调整。

watch

boolean = false

开启 watch 模式。这意味着在初始构建之后，webpack 将继续监视所有已解析文件的变化。

webpack.config.js

export default {
  // ...
  watch: true,
};

提示：在 webpack-dev-server 和 webpack-dev-middleware 中，watch 模式默认已启用。

watchOptions

object

用于自定义 watch 模式的一组选项：

webpack.config.js

export default {
  // ...
  watchOptions: {
    aggregateTimeout: 200,
    poll: 1000,
  },
};

watchOptions.aggregateTimeout

number = 20

在第一个文件发生变化之后、重新构建之前增加一个延迟。这让 webpack 可以将此时间段内发生的任何其他变更聚合到一次重新构建中。传入的值以毫秒为单位：

export default {
  // ...
  watchOptions: {
    aggregateTimeout: 600,
  },
};

watchOptions.ignored

RegExp string [string]

在某些系统中，监视大量文件可能会导致大量 CPU 或内存占用。可以使用正则表达式排除像 node_modules 这样的大型文件夹：

webpack.config.js

export default {
  // ...
  watchOptions: {
    ignored: /node_modules/,
  },
};

或者，也可以使用 glob 模式：

webpack.config.js

export default {
  // ...
  watchOptions: {
    ignored: "**/node_modules",
  },
};

也可以使用多个 glob 模式：

webpack.config.js

export default {
  // ...
  watchOptions: {
    ignored: ["**/files/**/*.js", "**/node_modules"],
  },
};

此外，你还可以指定绝对路径：

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

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

export default {
  // ...
  watchOptions: {
    ignored: [path.posix.resolve(__dirname, "./ignored-dir")],
  },
};

使用 glob 模式时，我们会通过 glob-to-regexp 将它们转换为正则表达式，因此在使用 glob 模式作为 watchOptions.ignored 的值之前，请确保你熟悉该工具。

提示：如果你使用 require.context，webpack 会监视你的整个目录。你需要忽略一些文件和/或目录，这样不希望的变更才不会触发重新构建。

watchOptions.poll

boolean = false number

传入 true 开启轮询模式，此时默认轮询间隔为 5007 毫秒；也可以指定一个以毫秒为单位的轮询间隔：

webpack.config.js

export default {
  // ...
  watchOptions: {
    poll: 1000, // Check for changes every second
  },
};

提示：如果监视功能对你不起作用，请尝试此选项。这可能有助于解决 NFS 以及 VirtualBox、WSL、容器或 Docker 中的机器所遇到的问题。在这些情况下，请使用轮询间隔并忽略大型文件夹（如 /node_modules/），以将 CPU 占用降至最低。

watchOptions.followSymlinks

在查找文件时跟随符号链接。这通常不是必需的，因为 webpack 已经通过 resolve.symlinks 解析符号链接。

• 类型：boolean

• 示例：

  js 复制代码

  export default {
    // ...
    watchOptions: {
      followSymlinks: true,
    },
  };

watchOptions.stdin

当 stdin 流结束时停止监视。

• 类型：boolean

• 示例：

  js 复制代码

  export default {
    // ...
    watchOptions: {
      stdin: true,
    },
  };

故障排查

如果你遇到任何问题，请参阅以下说明。webpack 可能漏掉文件变化的原因有很多种。

已看到变化但未处理

通过带 --progress 标志运行 webpack，来确认 webpack 是否收到了变化通知。如果保存时显示进度，但没有输出任何文件，则很可能是配置问题，而不是文件监视问题。

webpack --watch --progress

监视器数量不足

请确认你的系统中是否有足够可用的监视器（watcher）。如果该值过低，Webpack 的文件监视器将无法识别变化：

cat /proc/sys/fs/inotify/max_user_watches

Arch 用户，请将 fs.inotify.max_user_watches=524288 添加到 /etc/sysctl.d/99-sysctl.conf，然后执行 sysctl --system。Ubuntu 用户（以及其他可能适用的用户），请执行：echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p。

macOS 中的 fsevents 缺陷

在 macOS 上，某些场景下文件夹可能会损坏。请参阅这篇文章。

Windows 路径

由于 webpack 的许多配置选项（例如 __dirname + '/app/folder'）需要绝对路径，因此 Windows 的 \ 路径分隔符可能会破坏某些功能。

请使用正确的分隔符。例如 path.resolve(__dirname, 'app/folder') 或 path.join(__dirname, 'app', 'folder')。

Vim

在某些机器上，Vim 预设的 backupcopy 选项 为 auto。这可能会导致系统的文件监视机制出现问题。将此选项切换为 yes 可以确保保存时会创建文件的副本并覆盖原文件。

:set backupcopy=yes

在 WebStorm 中保存

使用 JetBrains WebStorm IDE 时，你可能会发现保存更改过的文件并不会像预期那样触发监视器。请尝试在设置中禁用 Back up files before saving 选项，该选项决定文件在覆盖原文件之前是否先保存到临时位置：取消勾选 File > {Settings|Preferences} > Appearance & Behavior > System Settings > Back up files before saving。在某些版本的 WebStorm 中，此选项可能名为 Use "safe write" (save changes to a temporary file first)。