我用Tanstack Start框架开发了一个React应用。我也已使用命令行工具成功将页面部署到Cloudflare：

npm run build
npx wrangler deploy

为了实现自动化，我定义了一个GitHub Actions工作流（参考这个链接的做法）：

name: Deploy

on:
    push:
        branches:
            - main

jobs:
    deploy:
        runs-on: ubuntu-latest
        name: Deploy
        steps:
            - uses: actions/checkout@v4
            - name: Deploy
              uses: cloudflare/wrangler-action@v3
              with:
                  apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
                  accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
                  command: deploy --config wrangler.jsonc

然而这出现了错误：

位于 "@tanstack/react-start/server-entry" 的入口文件未找到。

这是我的 wrangler.jsonc 文件：

{
    "$schema": "node_modules/wrangler/config-schema.json",
    "name": "intrinsic-michal-turczyn",
    "compatibility_date": "2025-09-02",
    "compatibility_flags": [
        "nodejs_compat"
    ],
    "main": "@tanstack/react-start/server-entry"
}

我搜索了一下，找到了这个已关闭的GitHub issue，但没有明确的解决方案。

我也尝试通过定义 src/server.ts 来覆盖服务器入口：

import handler from "@tanstack/react-start/server-entry";

export default {
    fetch(request: Request) {
        return handler.fetch(request);
    },
};

并在 wrangler.jsonc 中进行定义

"main": "./src/server.ts",

但在GitHub Actions中遇到了以下问题：

✘ [ERROR] Could not resolve "#tanstack-router-entry"
✘ [ERROR] Could not resolve "#tanstack-start-entry"
✘ [ERROR] Could not resolve "tanstack-start-manifest:v"
✘ [ERROR] Could not resolve "tanstack-start-server-fn-manifest:v"
✘ [ERROR] Could not resolve "tanstack-start-injected-head-scripts:v"

我应该如何部署这个应用？

解决方案

要点摘要

我需要在 cloudflare/wrangler-action@v3 任务之前加入安装和构建步骤：

- uses: actions/checkout@v4
- run: npm ci
- run: npm run build
- name: Deploy Cloudflare Workers
  uses: cloudflare/wrangler-action@v3
  with:
      apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
      accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

详细调查

+在 Cloudflare Worker中处理机密环境变量

在试验之后，我删除了仅本地创建的文件（被git忽略）：.wrangler/deploy/config.json，其内容如下：

{ "configPath": "..\\..\\dist\\server\\wrangler.json", "auxiliaryWorkers": [] }

我在想，删除这类文件会有什么影响。让我惊讶的是，在删除该文件并在本地运行时、wrangler deploy 我居然能够重现我在Github Action中遇到的错误！

位于 "@tanstack/react-start/server-entry" 的入口文件未找到。

因此，这显然是一个指示，表明wrangler实际上找不到合适的配置文件。

于是我决定从头开始写我的Github Action YML文件：

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: '25'
            - run: npm install -g wrangler
            - run: ls -la
            - run: wrangler deploy --config ./dist/server/wrangler.json
              env:
                  CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
                  CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

我使用 ls -la 来查看签出后我有哪些可用的内容。

结果很明显地显示我没有 .wrangler 目录，因此也没有 config.json。

不过上面的脚本失败，因为缺少会输出 dist 目录的 npm ci 和 npm build 命令。

添加它们之后：

...
- run: npm install -g wrangler
- run: npm ci
- run: npm run build
- run: wrangler deploy --config ./dist/server/wrangler.json
...

整个脚本成功运行并将应用正确部署到Cloudflare！

重要提示：wrangler部署会移除Worker中设置的环境变量，因此需要在 --keep-vars 处传递以保留已设置的环境变量。

编辑

受到成功经验的启发，我本以为可以通过以下调整让 cloudflare/wrangler-action@v3 正确运行

name: Deploy Worker
on:
    push:
        branches:
            - main
jobs:
    deploy:
        runs-on: ubuntu-latest
        timeout-minutes: 60
        steps:
            - uses: actions/checkout@v4
            - name: Build & Deploy Worker
              uses: cloudflare/wrangler-action@v3
              with:
                  apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
                  accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
                  command: deploy --config ./dist/server/wrangler.json

但它抱怨找不到 dist/server/wrangler.json 文件。

因此，借鉴我使用原始CLI命令实现的做法，我添加了步骤 npm ci 和 npm run build，使整件事生效。

最终，我得到的YML与文档中的几乎完全相同，只是在其中加入了 npm ci 和 npm run build 命令：

name: Deploy Worker
on:
    push:
        branches:
            - main

jobs:
    deploy:
        runs-on: ubuntu-latest
        timeout-minutes: 60
        name: Build App and Deploy Cloudflare Worker
        steps:
            - uses: actions/checkout@v4
            - run: npm ci
            - run: npm run build
            - name: Deploy Cloudflare Workers
              uses: cloudflare/wrangler-action@v3
              with:
                  apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
                  accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

然而，这也会移除Worker中的任何环境变量。我尝试将 secrets 参数传递给 cloudflare/wrangler-action@v3 动作。

此外，任何在HTML/客户端打包中可能使用的环境变量，需要在 npm run build 步骤中传递，因为此阶段可能已经生成了一些静态HTML，如果它引用了环境变量，我们需要在此步骤提供它们。

下面是最终、完全可用的Github Action YML，它在构建时正确设置环境变量，并且在Cloudflare Worker中也正确设置环境变量：

name: Deploy Worker
on:
    push:
        branches:
            - main

jobs:
    deploy:
        runs-on: ubuntu-latest
        timeout-minutes: 60
        name: Build App and Deploy Cloudflare Worker
        steps:
            - uses: actions/checkout@v4
            - run: npm ci
            # At this step, some static HTML is generated, so it needs environment variables
            # that could be used in client bundle.
            - run: npm run build
              env:
                  VITE_RECAPTCHA_SITE_KEY: ${{ secrets.VITE_RECAPTCHA_SITE_KEY }}
            - name: Deploy Cloudflare Workers
              uses: cloudflare/wrangler-action@v3
              with:
                  apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
                  accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
                  secrets: |
                      RECAPTCHA_SECRET_KEY
                      VITE_RECAPTCHA_SITE_KEY
              env:
                  RECAPTCHA_SECRET_KEY: ${{ secrets.RECAPTCHA_SECRET_KEY }}
                  VITE_RECAPTCHA_SITE_KEY: ${{ secrets.VITE_RECAPTCHA_SITE_KEY }}