[Bug] Canary Docker image fails to start due to missing @swc/helpers runtime file

该报错通常发生在 LobeChat Canary 版本的自托管 Docker 部署中,表现为数据库迁移成功后应用进程因缺少 @swc/helpers 运行时文件而崩溃。优先检查 Docker 镜像版本并关注修复 PR #18297 的合并状态。

快速结论:该报错通常发生在 LobeChat Canary 版本的自托管 Docker 部署中,表现为数据库迁移成功后应用进程因缺少 @swc/helpers 运行时文件而崩溃。优先检查 Docker 镜像版本并关注修复 PR #18297 的合并状态。

适用环境:LobeChat Canary Docker 镜像(lobehub/lobehub:canary)、Linux amd64 架构、Next.js 16.3.1、Node.js 24.19.0、Docker Compose 自托管部署。

最快修复方案:暂无已验证的一步修复方案。可优先尝试等待 PR #18297(fix(docker): include SWC helpers in runtime image)合并后,重新拉取最新的 Canary 镜像。

注意事项:该问题由镜像构建缺陷导致,并非宿主环境或 Compose 配置错误;在修复镜像发布前,任何本地配置调整都无法解决此问题。

问题场景

用户使用 Docker Compose 自托管部署 LobeChat Canary 版本镜像(lobehub/lobehub:canary)。镜像拉取并启动后,数据库迁移过程正常完成,但应用进程随即退出,导致服务无法启动。该问题与浏览器或客户端无关,属于纯服务端启动失败。

报错原文

Error: Cannot find module '/app/node_modules/.pnpm/next@16.3.1_.../node_modules/@swc/helpers/esm/_interop_require_default.js'
code: 'MODULE_NOT_FOUND'

原因分析

根本原因在于 Docker 镜像构建过程中的依赖复制逻辑缺陷。Next.js 16.3.1 的 standalone 构建输出保留了指向 @swc/helpers 的 pnpm 符号链接,但运行时镜像在复制依赖时仅保留了 pgdrizzle-orm/deps 目录,导致这些符号链接的目标文件缺失。此问题直接存在于已发布的镜像中,可通过直接运行镜像复现,与宿主环境或 Compose 配置无关。

环境排查

  • 确认部署使用的镜像是否为 lobehub/lobehub:canary 及具体镜像 digest(如 sha256:a80c0c6d928df4b5c4582c59eb05c8d5d849c239bc133cb374ba7b27af6395f8)。
  • 确认运行的架构是否为 linux/amd64
  • 确认 Node.js 和 Next.js 版本(Issue 中记录为 Node.js 24.19.0、Next.js 16.3.1)。
  • 检查 Docker Compose 配置,确保没有挂载指向 /app/app/node_modules,以免干扰问题复现。

解决步骤

  1. 确认当前使用的 Canary 镜像是否包含修复:PR #18297 通过将 @swc+helpers@* 虚拟存储目录复制到 /runtime-deps/,并在最终应用阶段使用 COPY --from=builder /runtime-deps/ /app/node_modules/.pnpm/ 将 SWC helpers 加入运行时镜像。
  2. 关注 PR #18297 合并状态,合并后重新拉取 Canary 镜像:docker compose pull lobe
  3. 重建并重启容器:docker compose up -d --force-recreate lobe
  4. 查看日志确认启动是否成功:docker compose logs --tail=200 lobe
  5. 如需自行验证镜像中文件是否存在,可在镜像内执行检查脚本,确认 _interop_require_default.js 文件状态为 OK

验证方法

重新拉取镜像并重启容器后,通过 docker compose logs --tail=200 lobe 查看应用日志,确认不再出现 MODULE_NOT_FOUND 错误,且 LobeChat 服务能够正常监听端口并响应请求。也可直接在镜像内运行检查脚本,确认 /app/node_modules/.pnpm/next@*/node_modules/@swc/helpers/esm/_interop_require_default.js 文件存在。

参考来源

lobehub/lobehub #18323

这个方案解决了吗?

celebrityanime
celebrityanime
文章: 18794

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注