Misskey开发模式下Vite代理配置的优化实践

背景与问题分析

Misskey作为一款开源社交网络软件，在开发模式下使用Vite作为前端构建工具。开发过程中发现，当配置了自定义域名和HTTPS后，某些特定类型的请求无法正确代理到后端服务，而是返回了Vite的index.html或空响应。这主要影响了以下功能：

1. ActivityPub协议相关的请求（如用户信息查询）
2. 带有数字签名的请求（如其他实例发起的inbox操作）
3. Bull任务队列仪表板访问

技术细节解析

问题的核心在于Vite开发服务器的代理配置未能正确处理这些特殊请求。具体表现为：

• 对于Accept头包含application/activity+json的ActivityPub请求
• 对于带有Signature头的签名请求
• 对于/queue路径的Bull仪表板访问

这些请求本应被代理到后端Node.js服务，但实际上却被Vite开发服务器拦截处理。

解决方案实现

通过分析请求特征，我们实现了智能路由的代理配置方案：

function varyHandler(req: IncomingMessage) {
    const path = req.url ?? '';

    // 排除Vite内部使用的路径
    if (path.startsWith('/@vite/') || path.startsWith('/@fs/') || path.startsWith('/@id/')) {
        return req.url;
    }

    // 识别ActivityPub请求和签名请求
    const isActivityPub = req.headers.accept?.includes('application/activity+json');
    const isSigned = req.headers.signature != null;
    
    if (isActivityPub || isSigned) {
        return null; // 代理到后端
    }

    return '/index.html'; // 其他请求走Vite
}

同时增加了对Bull仪表板路径的特殊处理：

proxy: {
    '^/@.*': {
        target: httpUrl,
        bypass: varyHandler,
    },
    '^/queue': { // Bull仪表板路径
        target: httpUrl,
        bypass: varyHandler,
    }
}

开发环境选择

Misskey提供了两种开发模式选择：

1. 默认模式：使用Vite开发服务器，支持热模块替换(HMR)，但需要上述代理配置优化
2. 后端优先模式：通过MK_DEV_PREFER=backend pnpm dev启动，所有请求都经过后端，但会失去部分HMR功能

需要注意的是，在后端优先模式下，由于WebSocket处理机制的原因，Vite的HMR功能可能会失效。这是因为后端服务会拦截所有WebSocket连接，包括Vite用于HMR的WebSocket连接。

配置合并优化

在解决过程中还发现，本地开发配置(vite.config.local-dev.ts)会完全覆盖默认配置，导致某些重要设置丢失。理想的做法是实现配置对象的深度合并，而非简单覆盖。这提示我们需要：

1. 开发一个配置合并工具函数
2. 确保关键安全头（如X-Frame-Options）不被意外覆盖

总结与最佳实践

对于Misskey开发者，建议：

1. 常规前端开发使用默认模式，配合优化后的代理配置
2. 涉及后端深度集成的开发使用后端优先模式
3. 注意检查配置合并情况，确保安全设置生效
4. 对于WebSocket相关功能开发，需要特别注意HMR的工作状态

这种智能代理方案不仅解决了当前问题，还为未来可能出现的类似路由决策需求提供了可扩展的框架结构。