Medusa.js项目中Vite安全配置导致请求被拦截的解决方案

问题背景

在Medusa.js项目升级到2.4.0版本后，许多开发者遇到了一个常见问题：管理后台界面显示"Blocked request. This host ('xx') is not allowed"的错误提示。这个问题源于Vite 6.1.0版本引入的一项安全增强功能，该功能默认只允许localhost作为开发环境的主机名。

问题本质

Vite作为现代前端构建工具，在6.1.0版本中加强了安全性，新增了server.allowedHosts配置项。这个配置默认在生产环境(NODE_ENV=production)下不做限制，但在开发环境下会严格检查请求来源，只允许localhost访问。

解决方案详解

生产环境解决方案

如果问题出现在生产环境，说明项目没有正确设置NODE_ENV环境变量。正确的做法是：

1. 确保package.json中的启动脚本明确设置了NODE_ENV：

"scripts": {
  "start": "NODE_ENV=production medusa start"
}

2. 在Docker部署时，确保Dockerfile中设置了环境变量：

ENV NODE_ENV=production

3. 在AWS AppRunner等云服务中，确保在环境变量配置中设置了NODE_ENV=production

开发环境解决方案

如果确实需要在开发环境下允许特定域名访问，可以通过修改medusa-config.ts配置文件来实现：

import { defineConfig, loadEnv } from "@medusajs/framework/utils";

loadEnv(process.env.NODE_ENV || "development", process.cwd());

export default defineConfig({
  admin: {
    vite: () => ({
      server: {
        allowedHosts: [".yourdomain.com"] // 注意前面的点号
      }
    })
  }
});

重要注意事项：

• allowedHosts数组中的域名应该只包含主机部分，并以点号开头
• 不要包含协议(如http://)或路径
• 点号前缀表示允许该域名及其所有子域名

常见误区

1. 错误配置域名格式：

   • 错误示例：allowedHosts: ["https://www.yourdomain.com"]
   • 正确示例：allowedHosts: [".yourdomain.com"]

2. 错误放置配置文件：

   • 应该在medusa-config.ts中配置，而不是vite.config.js

3. 忽略环境变量：

   • 生产环境应该优先通过设置NODE_ENV解决，而不是依赖allowedHosts

技术原理深入

Vite的这一安全变更实际上是遵循了现代Web开发的安全最佳实践。它通过限制可访问的主机名，有效防止了DNS重绑定等攻击。在开发环境下，这种限制可以防止开发者无意中将开发服务器暴露在不安全的网络中。

Medusa.js作为全栈框架，其管理后台使用Vite作为构建工具。当项目升级到使用Vite 6.1.0+版本时，这一安全特性会自动生效，导致之前能正常工作的部署突然出现访问限制。

最佳实践建议

1. 生产环境：

   • 始终确保NODE_ENV=production
   • 不需要配置allowedHosts

2. 开发环境：

   • 本地开发使用localhost访问
   • 如需远程访问，配置具体的allowedHosts
   • 考虑使用内网专线而不是直接暴露开发服务器

3. 版本升级：

   • 升级Medusa版本时，注意检查依赖的Vite版本
   • 阅读Vite的更新日志，了解重大变更

通过正确理解这一安全机制的原理和配置方法，开发者可以既保证应用的安全性，又不会影响正常的开发和部署流程。