Vite插件v0.2.0:开发代理新升级

版本：0.2.0 | 协议：MIT | 依赖：Vite >=5.0.0 <8.0.0

写在前面

v0.2.0 的主题是：让开发代理更优雅，让代码更干净。

前端开发中，代理配置是连接本地开发与后端服务的桥梁。然而 Vite 原生的 server.proxy 配置分散在 vite.config.ts 中，缺乏环境切换、延迟模拟、请求日志等开发期常见需求。v0.2.0 新增的 proxyManager 插件，以声明式规则体系替代繁琐的 http-proxy-middleware 配置，支持环境切换、规则文件、请求日志、延迟模拟、响应修改和环境变量覆盖，将代理配置从构建配置中解耦为独立、可维护的规则体系。

同时，本版还从多个插件中提取了重复逻辑到 common 工具模块，修复了 proxyManager 的四个关键缺陷，整体代码质量显著提升。

本版重点：

升级方式：修改 devDependencies 中版本号为 ^0.2.0。无 Breaking Changes，完全向后兼容。

一、5 分钟快速上手

1.1 安装与最小配置

{"devDependencies": {"@meng-xi/vite-plugin": "^0.2.0"}}

import { proxyManager } from '@meng-xi/vite-plugin'export default defineConfig({	plugins: [proxyManager({			rules: [{ context: '/api', target: 'http://localhost:3000' }]})]})

1.2 立刻看到效果

启动开发服务器后，代理请求自动生效，终端输出请求日志：

ℹ️ [@meng-xi/vite-plugin:proxy-manager] 已加载 1 条代理规则 (环境: development)ℹ️ [@meng-xi/vite-plugin:proxy-manager] GET /api/users → 200 (45ms) [http://localhost:3000]

1.3 运行时访问规则数据

const plugin = proxyManager({ rules: [...] })// 开发服务器启动后...const rules = plugin.pluginInstance?.getResolvedRules?.() // 当前生效的代理规则

二、核心能力：proxyManager 开发代理

2.1 声明式规则体系

一条 ProxyRule 即定义一条完整的代理规则，替代 Vite 原生 server.proxy 中分散的配置：

proxyManager({	rules: [// 基本代理{ context: '/api', target: 'http://localhost:3000' },// 带路径重写{			context: '/upload',			target: 'http://oss.example.com',rewrite: path => path.replace(/^\/upload/, '/v2/files')},// 正则匹配{ context: /^\/(v1|v2)\//, target: 'http://legacy-api.example.com' },// WebSocket 代理{ context: '/ws', target: 'ws://localhost:8080', ws: true }]})

2.2 环境切换

通过 env 字段限定规则生效环境，自动按 NODE_ENV 过滤：

proxyManager({	rules: [{ context: '/api', target: 'http://localhost:3000', env: ['development'] },{ context: '/api', target: 'https://staging-api.example.com', env: ['staging'] },{ context: '/api', target: 'https://api.example.com', env: ['production'] }]})

2.3 请求日志

三级日志输出，满足不同调试需求：

proxyManager({	rules: [...],	logLevel: 'verbose' // 输出：GET /api/users → 200(45ms) [http://localhost:3000]})

2.4 延迟模拟

模拟慢网络环境，测试 Loading 状态和超时处理：

proxyManager({	rules: [// 固定延迟 500ms{ context: '/api', target: 'http://localhost:3000', delay: 500 },// 随机延迟 200~800ms{ context: '/slow-api', target: 'http://localhost:3000', delay: { min: 200, max: 800 } }],// 全局默认延迟（对未配置 delay 的规则生效）	defaultDelay: { min: 100, max: 300 }})

2.5 响应修改

在代理响应返回客户端前修改 JSON 响应体，用于 Mock 数据或字段脱敏：

proxyManager({	rules: [{			context: '/api/users',			target: 'http://localhost:3000',modifyResponse: (body, proxyRes) => {// 脱敏手机号if(body?.phone) {					body.phone = body.phone.replace(/(\d{3})\d{4}(\d{4})/, '$1****$2')}return body}}]})

2.6 环境变量覆盖

通过环境变量动态覆盖代理目标，无需修改代码即可切换后端地址：

# .env.localPROXY_API_TARGET=http://staging-api.example.com

proxyManager({	rules: [// 当 PROXY_API_TARGET 存在时，target 被覆盖{ context: '/api', target: 'http://localhost:3000' }],	envPrefix: 'PROXY_' // 默认值})

环境变量命名规则：{context大写}_TARGET，如 context 为 /api 则读取 PROXY_API_TARGET。

2.7 规则文件

将代理规则抽离到独立文件，与 vite.config.ts 解耦：

// .proxyrc.tsimport type { ProxyRule } from '@meng-xi/vite-plugin'export default [{ context: '/api', target: 'http://localhost:3000', label: '本地 API' },{ context: '/ws', target: 'ws://localhost:8080', ws: true, label: 'WebSocket' }] satisfies ProxyRule[]

支持 .proxyrc.ts、.proxyrc.js、.proxyrc.mjs 三种格式，ESM 和 CJS 均可。

2.8 完整配置项

interface ProxyManagerOptions extends BasePluginOptions {	rules?: ProxyRule[] // 代理规则列表，默认 []	configFile?: string | false // 规则文件路径，默认 '.proxyrc.ts'	logLevel?: 'none' | 'basic' | 'verbose' // 日志级别，默认 'basic'	defaultDelay?: DelayConfig // 全局默认延迟，默认 false	envPrefix?: string // 环境变量前缀，默认 'PROXY_'}

ProxyRule 类型：

继承 BasePluginOptions 通用配置：enabled、verbose、errorStrategy。

三、Bug 修复

v0.2.0 修复了 proxyManager 插件中四个影响代理正确性与可观测性的关键缺陷：

3.1 modifyResponse 不生效

问题：配置 modifyResponse 后，代理响应未被修改即返回客户端。

原因：实现仅修改了 content-length 响应头，未将修改后的内容写入客户端响应流。

修复：收集代理响应 chunks → 解析 JSON → 应用 modifyResponse 回调 → 通过 res.end() 写回修改后内容。

// 修复后的核心逻辑proxy.on('proxyRes', (proxyRes, _req, res) => {const chunks: Buffer[] = []	proxyRes.on('data', (chunk: Buffer) => chunks.push(chunk))	proxyRes.on('end', () => {const body = Buffer.concat(chunks).toString()try {const parsed = JSON.parse(body)const modified = rule.modifyResponse!(parsed, proxyRes)if (modified !== undefined) {const modifiedBody = JSON.stringify(modified)				res.setHeader('content-length', Buffer.byteLength(modifiedBody))				res.end(modifiedBody)return}} catch {/* 非 JSON 响应，跳过修改 */}		res.end(body)})})

3.2 .mjs 规则文件加载失败

问题：.proxyrc.mjs 配置文件无法加载，报 require() of ES Module 错误。

原因：loadConfigFile 使用同步 require() 加载配置文件，无法处理 ESM .mjs 文件。

修复：改为 async 函数，.mjs 使用 await import() 动态导入，其他扩展名仍用 require()。

3.3 日志 duration 不含延迟时间

问题：配置延迟模拟后，日志输出的 duration 不包含延迟时间，与实际体验不符。

原因：延迟中间件先于日志中间件注册，导致 startTime 在延迟执行之后才记录。

修复：调整中间件注册顺序——日志中间件先注册（先执行）记录 startTime，延迟中间件后注册（后执行）。

3.4 RegExp context 生成无效环境变量名

问题：context 为正则表达式时，resolveTargetFromEnv 拼接出非法环境变量名（如 PROXY_/^\/API/_TARGET）。

原因：未对 RegExp 类型的 context 做类型守卫。

修复：增加 typeof context === 'string' 检查，RegExp context 跳过环境变量解析。

四、Common 工具模块增强

v0.2.0 从多个插件中提取了重复出现的逻辑到 common 目录，消除冗余代码：

4.1 common/format — 新增 parseTemplateWithDelimiter

通用模板解析函数，支持自定义左右分隔符，从 envGuard 插件中提取：

import { parseTemplateWithDelimiter } from '@meng-xi/vite-plugin/common/format'// 默认 {{ }} 分隔符parseTemplateWithDelimiter('Hello {{name}}!', { name: 'World' })// 'Hello World!'// 自定义分隔符parseTemplateWithDelimiter('Hello {name}!', { name: 'World' }, '{', '}')// 'Hello World!'// formatDate 内部使用此函数，分隔符为 { 和 }parseTemplateWithDelimiter('{YYYY}-{MM}-{DD}', getDateFormatParams(), '{', '}')// '2026-06-17'

安全特性：

• 键名中的正则特殊字符自动转义，避免正则注入
• 值中的 $ 安全处理，避免 $1****$2')}))}return body}}]})

# .env.local — 切换到预发布环境PROXY_API_TARGET=https://staging-api.example.comPROXY_UPLOAD_TARGET=https://staging-oss.example.com

// .proxyrc.tsimport type { ProxyRule } from '@meng-xi/vite-plugin'export default [{ context: '/api', target: 'http://localhost:3000', label: 'API 服务' },{ context: '/upload', target: 'http://localhost:4000', label: '上传服务' },{ context: '/ws', target: 'ws://localhost:8080', ws: true, label: 'WebSocket' }] satisfies ProxyRule[]

// vite.config.tsproxyManager({	configFile: '.proxyrc.ts',	envPrefix: 'PROXY_',	logLevel: 'verbose'})

import { defineConfig } from 'vite'import { imageOptimizer, assetManifest, proxyManager } from '@meng-xi/vite-plugin'export default defineConfig({	plugins: [proxyManager({			rules: [{ context: '/api', target: 'http://localhost:3000', delay: { min: 100, max: 300 } }],			logLevel: 'verbose'}),imageOptimizer({			convertToWebp: { png: true, jpeg: true },			keepOriginal: true,			quality: { webp: 75 }}),assetManifest({			publicPath: 'https://cdn.example.com/',			injectRuntime: true})]})

// 迁移前export default defineConfig({	server: {		proxy: {'/api': {				target: 'http://localhost:3000',				changeOrigin: true,rewrite: path => path.replace(/^\/api/, '')}}}})// 迁移后export default defineConfig({	plugins: [proxyManager({			rules: [{					context: '/api',					target: 'http://localhost:3000',					changeOrigin: true,rewrite: path => path.replace(/^\/api/, '')}],			logLevel: 'basic'})]})