- **类型：** `string | Object`
- **默认值：** `null`

该选项用于在开发环境下启用基于 [whistle](https://wproxy.org/whistle/) 的全局代理，可以用来查看、修改 HTTP/HTTPS 请求、响应、也可以用作代理服务器。

### 注册插件

使用该选项前，你需要提前安装和注册 `@modern-js/plugin-proxy` 插件：

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs command="add @modern-js/plugin-proxy -D" />

安装完成后，在 `modern.config.ts` 文件中注册插件：

```ts title="modern.config.ts"
import { appTools, defineConfig } from '@modern-js/app-tools';
import { proxyPlugin } from '@modern-js/plugin-proxy';

export default defineConfig({
  plugins: [appTools(), proxyPlugin()],
});
```

### Object 类型

`dev.proxy` 的值为 `Object` 时，对象的 `key` 对应匹配的 `pattern`，对象的 `value` 对应匹配的 `target`。

例如：

```ts title="modern.config.ts"
export default defineConfig({
  dev: {
    proxy: {
      'https://www.baidu.com': 'https://google.com.hk',
      //可以通过 file 协议直接返回静态文件。
      'https://example.com/api': 'file://./data.json',
    },
  },
});
```

请参考 [whistle - 匹配模式](https://wproxy.org/whistle/pattern.html) 来了解详细用法。

### String 类型

`dev.proxy` 的值为 `string` 时， 可以用来指定单独的代理文件，例如：

```ts title="modern.config.ts"
export default defineConfig({
  dev: {
    proxy: './proxy.js',
  },
});
```

```js title="proxy.js"
module.exports = {
  name: 'my-app',
  rules: `
    ^example.com:8080/api/***   http://localhost:3001/api/$
  `,
};
```

### 启动代理

执行 `dev`, 提示如下时，即代理服务器启动成功：

```bash
  Local:    http://localhost:8080/
  Network:  http://192.168.0.1:8080/

info      Starting proxy server.....
success   Proxy server start on localhost:8899
```

访问 `localhost:8899`, 可以在 UI 界面上查看 Network 以及配置代理规则：

![proxy ui 界面](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/dev-proxy.png)

:::info
https 代理自动安装证书需要获取 root 权限, 请根据提示输入密码即可。**密码仅在信任证书时使用，不会泄漏或者用于其他环节**。

:::
