# watchpack 中文文档

规范地址：https://npmcn.com/package/watchpack/

版本：2\.6\.4
npm 元数据更新时间：2026-11-07T14:53:28.859Z
中文译文更新时间：2026-11-05T16:19:35.783Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/watchpack
原文对照：https://npmcn.com/package/watchpack/?lang=original
项目主页：https://github.com/webpack/watchpack
源码仓库：https://github.com/webpack/watchpack

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：122 kB，19 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=10\.13\.0
- 运行依赖：1 个
- 首次发布：2014-10-09T06:48:51.514Z
- 最新版本发布：2026-11-07T14:53:28.531Z
- 近 30 天下载量：252891187（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：66（近 12 个月 8 个）

## 中文简介

用于目录和文件监视的 Wrapper 库 .

## 安装

```sh
npm install watchpack
```

也可以使用：`pnpm add watchpack`、`yarn add watchpack`、`bun add watchpack`

## README

# 手表包装

用于目录和文件监视的 Wrapper 库 .

[![Test](https://github.com/webpack/watchpack/actions/workflows/test.yml/badge.svg)](https://github.com/webpack/watchpack/actions/workflows/test.yml) [![Codecov](https://codecov.io/gh/webpack/watchpack/graph/badge.svg?token=8xk2OrrxWm)](https://codecov.io/gh/webpack/watchpack) [![Downloads](https://img.shields.io/npm/dm/watchpack.svg)](https://www.npmjs.com/package/watchpack)

## 概念

watchpack高水平API不直接向监视者映射. 取而代之的是三级架构,确保每个目录只存在单一的监视器.

-   高级API请求 `DirectoryWatchers` 从a `WatcherManager`,它确保只有一个 `DirectoryWatcher` 每个目录创建.
-   一个用户面 `Watcher` 可从 `DirectoryWatcher` 并提供一个过滤视图 `DirectoryWatcher`。 。 。 .
-   参考数用于 `DirectoryWatcher` 财务报告和审定财务报表 `Watcher` 决定何时关闭它们.
-   真正的观察者是由 `DirectoryWatcher`。 。 。 .
-   档案从不直接观看. 这会让观察者数不高.
-   观行能从过去起. 这样观看可以在文件读取后开始.
-   共通链接没有被跟踪,而是被监视.

## API 密码

```javascript
const Watchpack = require("watchpack");

const wp = new Watchpack({
    // options:
    aggregateTimeout: 1000,
    // fire "aggregated" event when after a change for 1000ms no additional change occurred
    // aggregated defaults to undefined, which doesn't fire an "aggregated" event

    poll: true,
    // poll: true - use polling with the default interval
    // poll: 10000 - use polling with an interval of 10s
    // poll defaults to undefined, which prefer native watching methods
    // Note: enable polling when watching on a network path
    // When WATCHPACK_POLLING environment variable is set it will override this option

    followSymlinks: true,
    // true: follows symlinks and watches symlinks and real files
    //   (This makes sense when symlinks has not been resolved yet, comes with a performance hit)
    // false (default): watches only specified item they may be real files or symlinks
    //   (This makes sense when symlinks has already been resolved)

    ignored: "**/.git",
    // ignored: "string" - a glob pattern for files or folders that should not be watched
    // ignored: ["string", "string"] - multiple glob patterns that should be ignored
    // ignored: ["string", /regexp/] - a mix of glob patterns and regular expressions that should be ignored
    // ignored: /regexp/ - a regular expression for files or folders that should not be watched
    // ignored: (entry) => boolean - an arbitrary function which must return truthy to ignore an entry
    // For all cases expect the arbitrary function the path will have path separator normalized to '/'.
    // All subdirectories are ignored too
});

// Watchpack.prototype.watch({
//   files: Iterable<string>,
//   directories: Iterable<string>,
//   missing: Iterable<string>,
//   startTime?: number
// })
wp.watch({
    files: listOfFiles,
    directories: listOfDirectories,
    missing: listOfNotExistingItems,
    startTime: Date.now() - 10000,
});
// starts watching these files and directories
// calling this again will override the files and directories
// files: can be files or directories, for files: content and existence changes are tracked
//        for directories: only existence and timestamp changes are tracked
// directories: only directories, directory content (and content of children, ...) and
//              existence changes are tracked.
//              assumed to exist, when directory is not found without further information a remove event is emitted
// missing: can be files or directories,
//          only existence changes are tracked
//          expected to not exist, no remove event is emitted when not found initially
// files and directories are assumed to exist, when they are not found without further information a remove event is emitted
// missing is assumed to not exist and no remove event is emitted

wp.on("change", (filePath, mtime, explanation) => {
    // filePath: the changed file
    // mtime: last modified time for the changed file
    // explanation: textual information how this change was detected
});

wp.on("remove", (filePath, explanation) => {
    // filePath: the removed file or directory
    // explanation: textual information how this change was detected
});

wp.on("aggregated", (changes, removals) => {
    // changes: a Set of all changed files
    // removals: a Set of all removed files
    // watchpack gives up ownership on these Sets.
});

// Watchpack.prototype.pause()
wp.pause();
// stops emitting events, but keeps watchers open
// next "watch" call can reuse the watchers
// The watcher will keep aggregating events
// which can be received with getAggregated()

// Watchpack.prototype.close()
wp.close();
// stops emitting events and closes all watchers

// Watchpack.prototype.getAggregated(): { changes: Set<string>, removals: Set<string> }
const { changes, removals } = wp.getAggregated();
// returns the current aggregated info and removes that from the watcher
// The next aggregated event won't include that info and will only emitted
// when futher changes happen
// Can also be used when paused.

// Watchpack.prototype.collectTimeInfoEntries(fileInfoEntries: Map<string, Entry>, directoryInfoEntries: Map<string, Entry>)
wp.collectTimeInfoEntries(fileInfoEntries, directoryInfoEntries);
// collects time info objects for all known files and directories
// this include info from files not directly watched
// key: absolute path, value: object with { safeTime, timestamp }
// safeTime: a point in time at which it is safe to say all changes happened before that
// timestamp: only for files, the mtime timestamp of the file

// Watchpack.prototype.getTimeInfoEntries()
const fileTimes = wp.getTimeInfoEntries();
// returns a Map with all known time info objects for files and directories
// similar to collectTimeInfoEntries but returns a single map with all entries

// (deprecated)
// Watchpack.prototype.getTimes()
const fileTimesOld = wp.getTimes();
// returns an object with all known change times for files
// this include timestamps from files not directly watched
// key: absolute path, value: timestamp as number
```

## 环境变量

-   `WATCHPACK_POLLING`: 设定时,将覆盖 `poll` 选项(见上文).
-   `WATCHPACK_RETRIES`: 重试的次数 `fs.lstat` 当它返回时 `EBUSY` (默认 : `3`用于Windows的抗病毒扫描仪, 索引器或编辑器可以短暂锁定文件——不用重试手表包 看见一个假象 `remove` 并停止跟踪文件。 设定为 `0` 或者说 `"false"` 以禁用重试.

## 常见问题

### watchpack 是什么？

用于目录和文件监视的 Wrapper 库 \.

### 如何安装 watchpack？

在项目目录运行 npm install watchpack，或使用 pnpm add / yarn add / bun add。

### watchpack 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### watchpack 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### watchpack 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=10\.13\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### watchpack 可以商用吗？

watchpack 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### watchpack 的下载量有多少？

根据 npm 官方下载统计，watchpack 在 2026/10/07 – 2026/11/05 这 30 天内被下载 252,891,187 次，日均约 8,429,706 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### watchpack 还在维护吗？

最新版本 2\.6\.4 发布于 2026/11/07（今天）；至今共发布 66 个版本，其中过去 12 个月发布了 8 个；首次发布于 2014/10/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。