> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# dev.watchFiles

- **类型：**

```ts
type WatchFileEvent = 'add' | 'change' | 'unlink';

type WatchFiles = {
  paths: string | string[];
  events?: WatchFileEvent[];
  type?: 'reload-page' | 'restart' | 'reload-server';
  //  chokidar 选项
  options?: ChokidarOptions;
};

type WatchFilesConfig = WatchFiles | WatchFiles[];
```

- **默认值：** `undefined`

监听指定文件和目录的变化。当文件发生变化时，可以触发页面重新加载，也可以重启 dev server 或监听构建。

## paths

- **类型：** `string | string[]`
- **默认值：** `undefined`

监视的文件或目录的路径，支持 glob 语法。可以是单个路径，也可以是多个路径组成的数组。

- 监听单个文件：

```ts title="rsbuild.config.ts"
export default {
  dev: {
    watchFiles: {
      paths: 'public/demo.txt',
    },
  },
};
```

- 使用 glob 匹配多个文件：

```ts title="rsbuild.config.ts"
export default {
  dev: {
    watchFiles: {
      paths: 'src/**/*.txt',
    },
  },
};
```

- 监听多个文件路径：

```ts title="rsbuild.config.ts"
export default {
  dev: {
    watchFiles: {
      paths: ['src/**/*.txt', 'public/**/*'],
    },
  },
};
```

:::tip
Glob 模式会在 watcher 启动时展开，因此不会包含之后新建的匹配路径。如需监听启动后可能新增的文件，请改为监听其父目录。

在所有平台上，glob 模式都应使用正斜杠（`/`）作为路径分隔符。请勿使用 `path.join()` 构造 glob 模式，因为它在 Windows 上会生成反斜杠，而反斜杠在 glob 语法中会被解释为转义符。

请使用字符串字面量或 `path.posix.join()` 构造相对 glob 模式。
:::

## events

- **类型：** `('add' | 'change' | 'unlink')[]`
- **默认值：** `['add', 'change', 'unlink']`

指定触发对应操作的文件事件：

- `add`：监听范围内检测到文件。默认仅对 watcher 启动后新增的文件触发；将 [`options.ignoreInitial`](#options) 设为 `false` 时，启动时已存在的文件也会触发该事件。
- `change`：监听范围内的文件发生变更。
- `unlink`：监听范围内的文件被删除。

例如，只在目录中新增或移除文件时触发重启：

```ts title="rsbuild.config.ts"
export default {
  dev: {
    watchFiles: {
      paths: './config',
      type: 'restart',
      events: ['add', 'unlink'],
    },
  },
};
```

## type

- **类型：** `'reload-page' | 'restart' | 'reload-server'`
- **默认值：** `'reload-page'`

指定当文件发生变化时，是触发页面重新加载，还是重启 dev server 或监听构建。

### reload-page

`reload-page` 表示当监听文件发生 [`events`](#events) 指定的事件时，浏览器中的页面会自动重新加载。默认情况下，新增、修改和删除都会触发重新加载。如果未明确指定 `type`，Rsbuild 默认采用 `reload-page`。

这可以用于监听一些静态资源文件的变化，例如 [public 目录](/zh/config/server/public-dir.md) 下的文件。

```ts title="rsbuild.config.ts"
export default {
  dev: {
    watchFiles: {
      type: 'reload-page',
      paths: 'public',
    },
  },
};
```

> 如果 [dev.hmr](/zh/config/dev/hmr.md) 和 [dev.liveReload](/zh/config/dev/live-reload.md) 都设置为 `false`，则页面将不会自动重新加载。

### restart

`restart` 会在执行 `rsbuild dev` 时请求重启 dev server，在执行 `rsbuild build --watch` 时请求重启监听构建。

这可以用于监听一些变更后需要重新初始化 Rsbuild 的配置文件。

例如，你在 `config` 目录下维护了一些公共配置文件，例如 `common.ts`，你希望这些文件发生变化时重启 dev server 或监听构建：

```ts title="rsbuild.config.ts"
import { commonConfig } from './config/common';

export default {
  ...commonConfig,
  dev: {
    watchFiles: {
      type: 'restart',
      paths: ['./config/*.ts'],
    },
  },
};
```

> 关于配置文件自动监听及重启行为，详见[配置文件监听](/zh/guide/configuration/rsbuild.md#configuration-file-watching)。

### reload-server

`reload-server` 是 `restart` 的废弃别名，为保证向后兼容，目前仍然支持。

## options

- **类型：** `ChokidarOptions`
- **默认值：** `undefined`

`watchFiles` 是基于 [chokidar v4](https://github.com/paulmillr/chokidar#getting-started) 实现的，你可以通过 `options` 传入 chokidar 的选项。

```ts title="rsbuild.config.ts"
export default {
  dev: {
    watchFiles: {
      paths: 'src/**/*.txt',
      options: {
        usePolling: false,
      },
    },
  },
};
```

## 传入数组

`dev.watchFiles` 支持传入一个数组，这允许你同时配置不同 `type` 的监听器，或是为不同的目录配置不同的 `watchOptions`。

```ts title="rsbuild.config.ts"
export default {
  dev: {
    watchFiles: [
      {
        type: 'reload-page',
        paths: 'public',
      },
      {
        type: 'restart',
        paths: ['./config/*.ts'],
      },
    ],
  },
};
```

## 说明

`watchFiles` 不适用于监听构建依赖的文件。当 Rsbuild 构建开始时，底层的 Rspack 默认会监听所有构建依赖，当这些文件发生变化时，会触发一次新的构建。

如果你希望当某些文件变化时，不触发重新构建，可以使用 Rspack 的 [watchOptions.ignored](https://rspack.rs/zh/config/watch#watchoptionsignored) 配置项。

> 详见 [模块热更新 - 文件监听](/zh/guide/advanced/hmr.md#file-watching)。

## 版本历史

| 版本     | 变更内容                                      |
| ------ | ----------------------------------------- |
| v2.1.8 | 新增 `events` 选项；`reload-page` 现在会响应文件新增和删除 |
| v2.1.7 | 新增 `restart` 类型，废弃 `reload-server`        |