如何通过 GitHub Actions 部署 TanStack Start 到 Cloudflare？

2026-11-04数据阿明

结论

工作流需要先安装项目依赖、运行 npm run build，再执行 wrangler deploy。你提供的本地成功流程包含构建步骤，但 GitHub Actions 目前只运行了 Wrangler 部署命令。由于 CI 使用独立环境，它不会自动获得本地安装的依赖或构建产物。

调整工作流

在部署动作前加入 Node.js 设置、依赖安装和构建步骤。例如，项目使用 npm 且已提交 package-lock.json 时，可以这样配置：

name: Deploy

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    name: Deploy
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Deploy
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: deploy --config wrangler.jsonc

示例中的 Node.js 版本应符合项目的运行环境要求。若项目使用 pnpm 或 Yarn，请改用对应的安装命令和锁文件缓存设置。npm ci 需要仓库中有与项目依赖一致的 package-lock.json。

关于入口和虚拟模块错误

首次报错显示 Wrangler 找不到 @tanstack/react-start/server-entry。在 CI 中安装依赖并运行与本地相同的构建流程，可以排查依赖未安装或构建未完成导致的缺失。

后续报错中出现的 #tanstack-router-entry、#tanstack-start-entry 和 tanstack-start-*-manifest:v，都是构建过程中使用的模块标识。你提供的工作流没有执行构建；直接让 Wrangler 处理 src/server.ts 时，这些模块可能还未生成或解析。因此，先补上完整的项目构建，再进行部署，并继续使用本地成功部署时的 wrangler.jsonc 配置。

如果补上安装和构建步骤后仍然报入口错误，请检查构建是否成功、CI 安装的依赖中是否包含 @tanstack/react-start，以及项目的 TanStack Start 配置是否与当前安装版本匹配。现有材料没有提供框架版本和构建脚本内容，无法确定是否还需要额外的 Cloudflare adapter 配置；请根据项目实际使用的版本确认部署配置。