Astro（+React）项目部署报错：找不到@astrojs/internal-helpers包

问题描述 #

我创建了一个Astro（+React）项目，本地使用Node v18.18.0执行node apps/server/entry.mjs命令可正常运行，但部署到服务器后执行相同命令时出现模块找不到错误：

Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@astrojs/internal-helpers' imported from /home/xxx/apps/server/entry.mjs
    at new NodeError (node:internal/errors:405:5)
    at packageResolve (node:internal/modules/esm/resolve:890:9)
    at moduleResolve (node:internal/modules/esm/resolve:939:20)
    at defaultResolve (node:internal/modules/esm/resolve:1132:11)
    at nextResolve (node:internal/modules/esm/loader:163:28)
    at ESMLoader.resolve (node:internal/modules/esm/loader:835:30)
    at ESMLoader.getModuleJob (node:internal/modules/esm/loader:424:18)
    at ModuleWrap.<anonymous> (node:internal/modules/esm/module_job:77:40)
    at link (node:internal/modules/esm/module_job:76:36) {
  code: 'ERR_MODULE_NOT_FOUND'
}

项目环境信息：

Astro                    v3.6.4
Node                     v18.18.0
System                   macOS (arm64)（本地）
Package Manager          npm
Output                   server
Adapter                  @astrojs/node
Integrations             @astrojs/solid-js
                         @astrojs/react
                         @astrojs/svelte

解决方案 #

• 重新完整安装服务器端依赖
  服务器端可能存在依赖安装不完整的情况，执行以下命令重新安装：

  npm install
  

  确保package-lock.json和本地保持一致，避免依赖版本差异导致的问题。

• 先执行构建命令再运行服务
  Astro的server输出模式需要先完成构建步骤，生成可执行的入口文件。在服务器上先运行：

  npm run build
  

  构建完成后再执行node apps/server/entry.mjs。

• 手动安装缺失的内部依赖
  @astrojs/internal-helpers是Astro的内部依赖，正常会自动引入，若服务器端未解析到，可手动安装：

  npm install @astrojs/internal-helpers
  

• 清理npm缓存后重装依赖
  若缓存损坏导致依赖安装异常，执行以下命令清理缓存并重新安装：

  npm cache clean --force
  rm -rf node_modules package-lock.json
  npm install
  

• 确认ES模块配置
  检查项目package.json中是否存在"type": "module"配置，确保服务器端Node.js使用ES模块解析模式，和本地保持一致。

内容的提问来源于stack exchange，提问作者Shautieh