Vercel部署Shopify Remix Hydrogen应用遇函数崩溃及unstable_singleFetch错误

可能原因及对应修复方案 #

1. Remix版本与Hydrogen/Vercel适配器不兼容 #

• 查看package.json里的Remix相关依赖，确保@remix-run/node、@remix-run/vercel和@shopify/hydrogen版本匹配。Hydrogen对Remix版本有明确要求，建议锁定到Hydrogen官方推荐的版本范围。
• 重新执行npm install或yarn install，确保所有依赖版本一致。

2. Vercel适配器配置错误 #

• 检查Vercel入口文件（通常是api/vercel.ts或server.ts），确认正确导入并使用Remix的Vercel适配器，避免错误调用unstable_singleFetch。正确的初始化示例：

  import { createRequestHandler } from '@remix-run/vercel';
  import * as build from '@remix-run/dev/server-build';
  
  export default createRequestHandler({
    build,
    mode: process.env.NODE_ENV,
  });
  

• 如果代码中手动调用了unstable_singleFetch，确认当前Remix版本支持该API，或改用稳定替代方案。

3. Vite构建配置缺失 #

• 检查vite.config.ts，确保正确配置Hydrogen插件，保证构建时包含所有必要的服务端代码：

  import { defineConfig } from 'vite';
  import hydrogen from '@shopify/hydrogen/plugin';
  
  export default defineConfig({
    plugins: [hydrogen()],
  });
  

• 确认Vercel的构建命令正确，比如package.json中build脚本指向Hydrogen的构建命令：

  {
    "scripts": {
      "build": "hydrogen build"
    }
  }
  

4. 环境变量或运行时配置问题 #

• 确保Vercel项目中配置了所有必要的Hydrogen环境变量（如SHOPIFY_STOREFRONT_API_TOKEN、SHOPIFY_STORE_DOMAIN等），缺失环境变量可能导致服务端初始化失败。
• 检查Vercel的Node.js运行时版本，确保使用18.x及以上版本，符合Hydrogen的要求。

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