MedusaJS项目部署至Dokku服务器启动失败问题排查

我新建了一个MedusaJS项目，本地开发环境运行完全正常，但尝试将API和Admin模块部署到Dokku服务器后，项目无法启动。通过在本地设置生产环境变量，复现了和服务器上相同的错误：

NODE_ENV=production yarn start

构建过程无报错，但启动时直接崩溃，日志输出如下：

➜  backend git:(enable-redis) ✗ NODE_ENV=production yarn start
yarn run v1.22.19
$ cross-env yarn build && medusa start
$ cross-env yarn clean && yarn build:server && yarn build:admin
$ cross-env ./node_modules/.bin/rimraf dist
$ cross-env yarn clean && tsc -p tsconfig.server.json
$ cross-env ./node_modules/.bin/rimraf dist
$ cross-env medusa-admin build

✔ Webpack
  Compiled successfully in 19.94s

{"level":"error","message":"Error starting server","stack":[{"columnNumber":15,"fileName":"/Users/artur/projects/enigma/liderpav/backend/node_modules/@medusajs/medusa/dist/loaders/config.js","functionName":"errorHandler","lineNumber":23,"methodName":null,"native":false,"typeName":null},{"columnNumber":9,"fileName":"/Users/artur/projects/enigma/liderpav/backend/node_modules/@medusajs/medusa/dist/loaders/config.js","functionName":null,"lineNumber":45,"methodName":null,"native":false,"typeName":null},{"columnNumber":57,"fileName":"/Users/artur/projects/enigma/liderpav/backend/node_modules/@medusajs/medusa/dist/loaders/index.js","functionName":null,"lineNumber":268,"methodName":null,"native":false,"typeName":null},{"columnNumber":23,"fileName":"/Users/artur/projects/enigma/liderpav/backend/node_modules/@medusajs/medusa/dist/loaders/index.js","functionName":"step","lineNumber":56,"methodName":null,"native":false,"typeName":null},{"columnNumber":53,"fileName":"/Users/artur/projects/enigma/liderpav/backend/node_modules/@medusajs/medusa/dist/loaders/index.js","functionName":"Object.next","lineNumber":37,"methodName":"next","native":false,"typeName":Object},{"columnNumber":71,"fileName":"/Users/artur/projects/enigma/liderpav/backend/node_modules/@medusajs/medusa/dist/loaders/index.js","functionName":null,"lineNumber":31,"methodName":null,"native":false,"typeName":null},{"columnNumber":null,"fileName":null,"functionName":"new Promise","lineNumber":null,"methodName":null,"native":false,"typeName":null},{"columnNumber":12,"fileName":"/Users/artur/projects/enigma/liderpav/backend/node_modules/@medusajs/medusa/dist/loaders/index.js","functionName":"__awaiter","lineNumber":27,"methodName":null,"native":false,"typeName":null},{"columnNumber":12,"fileName":"/Users/artur/projects/enigma/liderpav/backend/node_modules/@medusajs/medusa/dist/loaders/index.js","functionName":null,"lineNumber":262,"methodName":null,"native":false,"typeName":null},{"columnNumber":72,"fileName":"/Users/artur/projects/enigma/liderpav/backend/node_modules/@medusajs/medusa/dist/commands/start.js","functionName":null,"lineNumber":66,"methodName":null,"native":false,"typeName":null}],"timestamp":"2024-04-17 10:51:17"}
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

日志没有给出具体错误原因，请问我遗漏了什么配置或步骤？

排查建议 #

• 检查生产环境核心配置
  生产环境下Medusa不会使用开发默认的sqlite数据库，必须在medusa-config.js中明确配置database_url、redis_url，同时确认JWT_SECRET、ADMIN_JWT_SECRET这些敏感变量已设置，开发环境的默认值不会在生产模式中生效。

• 获取详细错误日志
  修改启动命令开启debug日志：NODE_ENV=production LOG_LEVEL=debug yarn start，或者直接查看@medusajs/medusa/dist/loaders/config.js第23行的错误捕获逻辑，这里应该会记录具体错误原因；在Dokku上执行dokku logs <app-name>查看实时服务器日志，获取更多上下文信息。

• 验证构建产物完整性
  手动删除dist目录后重新构建，避免缓存干扰：rimraf dist && NODE_ENV=production yarn build && yarn start，检查dist/server和dist/admin目录是否完整生成。

• Dokku部署配置校验

  1. 通过dokku config:show <app-name>确认所有生产环境变量已正确注入；
  2. 检查端口映射，Medusa默认API端口9000、Admin端口7000，需在Dokku中配置端口暴露，或通过PORT变量指定；
  3. 在项目根目录添加Procfile，内容为web: yarn start，确保Dokku使用正确的启动命令。

内容的提问来源于stack exchange，提问作者artur.prado