Medusa项目Docker部署中Admin仪表盘Widget加载问题解析

问题背景

在使用Medusa 2.4.0版本构建电商系统时，开发者在Docker环境中部署Admin仪表盘时遇到了Widget加载失败的问题。具体表现为添加自定义Widget后，Admin界面无法正常加载，控制台显示MIME类型错误。

核心问题分析

1. 路径冲突问题

Docker构建文件中将工作目录设置为/app，这与Medusa Admin默认的静态资源路径/app产生了冲突。这种路径重叠会导致Vite构建的资源无法被正确加载。

2. 构建流程不规范

项目直接使用yarn build后启动，没有遵循Medusa推荐的完整构建流程。正确的生产环境构建应该包含专门的构建步骤和依赖安装过程。

3. 环境变量配置不当

从错误信息可以看出，系统在运行时仍然使用了开发环境的配置，特别是Vite的热更新(HMR)代码被注入到了生产环境的HTML中。这表明NODE_ENV环境变量未被正确设置为production。

解决方案

1. 修改Docker工作路径

建议将Dockerfile中的WORKDIR修改为与Medusa Admin默认路径不同的值，例如：

WORKDIR /usr/src/app

2. 完善构建流程

按照Medusa官方推荐的构建流程，Dockerfile应该包含以下关键步骤：

# 安装依赖
RUN yarn install

# 构建项目
RUN yarn build

# 进入构建目录安装生产依赖
WORKDIR /.medusa/server
RUN yarn install --production

3. 正确配置环境变量

对于无法直接设置NODE_ENV的环境（如AWS App Runner），可以通过以下方式解决：

• 在package.json中修改启动脚本：

"scripts": {
  "start": "medusa start --prod"
}

• 或者在Dockerfile中使用ENV指令：

ENV NODE_ENV=production

最佳实践建议

1. 分离开发与生产配置：确保开发环境和生产环境使用不同的配置文件和构建流程。

2. 构建缓存优化：在Dockerfile中合理使用缓存层，加速构建过程：

COPY package.json yarn.lock ./
RUN yarn install
COPY . .

3. 资源路径检查：在部署前验证所有静态资源的路径是否正确，特别是使用自定义路径时。

4. 环境一致性：确保本地开发环境与生产环境的Node.js版本、依赖版本等完全一致。

总结

Medusa项目在Docker环境中的部署需要特别注意路径配置、构建流程和环境变量设置。通过调整工作目录、完善构建步骤和正确配置生产环境，可以有效解决Admin仪表盘Widget加载失败的问题。这些经验不仅适用于当前版本，也为后续版本的部署提供了参考方案。