托管与部署

托管（Hosting）是把你的应用部署到互联网上、让用户可以访问的过程。这是任何 Web 开发项目的关键一环，确保你的应用能被全世界访问。TanStack Start 支持 Vite 和 Rsbuild，为你提供灵活构建产物，适配不同的托管平台和运行时。

该用什么？

TanStack Start 设计上适用于任何托管平台，所以如果你心里已经有了托管平台，可以用 TanStack Start 提供的全栈 API 把应用部署到那里。

不过，由于托管是影响应用性能、可靠性和可扩展性最关键的因素之一，我们建议使用我们的官方托管合作伙伴之一：Cloudflare、Netlify 或 Railway。

部署

选定部署目标后，可以按照下面的部署指南，把 TanStack Start 应用部署到你选择的托管平台：

Cloudflare Workers（官方合作伙伴）：部署到 Cloudflare Workers
Netlify（官方合作伙伴）：部署到 Netlify
Railway（官方合作伙伴）：部署到 Railway
Nitro：使用 Nitro 部署
Vercel：部署到 Vercel
Node.js 服务器 / Docker：部署到 Node.js 服务器
Bun：部署到 Bun 服务器
Appwrite Sites：部署到 Appwrite Sites
……还会有更多！

Cloudflare Workers ⭐ 官方合作伙伴

Cloudflare

部署到 Cloudflare Workers 时，在用户能使用你的应用之前，需要先完成几个额外的步骤。官方的 Cloudflare Workers 方案目前通过 @cloudflare/vite-plugin 使用 Vite。

安装 @cloudflare/vite-plugin 和 wrangler

pnpm add -D @cloudflare/vite-plugin wrangler

把 Cloudflare 插件添加到你的 vite.config.ts 文件

// vite.config.ts
import { defineConfig } from 'vite'
import { tanstackStart } from '@tanstack/react-start/plugin/vite'
import { cloudflare } from '@cloudflare/vite-plugin'
import viteReact from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [
    cloudflare({ viteEnvironment: { name: 'ssr' } }),
    tanstackStart(),
    viteReact(),
  ],
})

添加一个 wrangler.jsonc 配置文件

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

修改 package.json 中的脚本

{
  "scripts": {
    "dev": "vite dev",
    "build": "vite build && tsc --noEmit",
    // ============ 👇 remove this line ============
    "start": "node .output/server/index.mjs",
    // ============ 👇 add these lines ============
    "preview": "vite preview",
    "deploy": "npm run build && wrangler deploy",
    "cf-typegen": "wrangler types"
  }
}

用 Wrangler 登录，向你的 Cloudflare 账户认证。

npx wrangler login

或者如果使用 pnpm：

pnpm dlx wrangler login

用 wrangler whoami 查看当前用户。

部署

pnpm run deploy

用它们的一键部署流程把应用部署到 Cloudflare Workers，然后就大功告成了！

Cloudflare Workers 的完整 TanStack Start 示例见这里。

Netlify ⭐ 官方合作伙伴

Netlify

官方的 Netlify 方案目前通过 @netlify/vite-plugin-tanstack-start 使用 Vite，它会把你的构建配置成适合 Netlify 部署，并在本地开发中提供完整的 Netlify 生产平台模拟：

npm install --save-dev @netlify/vite-plugin-tanstack-start
# or...
pnpm add --save-dev @netlify/vite-plugin-tanstack-start
# or yarn, bun, etc.

// vite.config.ts
import { defineConfig } from 'vite'
import { tanstackStart } from '@tanstack/react-start/plugin/vite'
import netlify from '@netlify/vite-plugin-tanstack-start' // ← add this
import viteReact from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [
    tanstackStart(),
    netlify(), // ← add this (anywhere in the array is fine)
    viteReact(),
  ],
})

最后，用 Netlify CLI 部署你的应用：

npx netlify deploy

如果这是一个新的 Netlify 项目，它会提示你初始化，并自动为你配置好构建设置。

更详细的文档请看完整的 TanStack Start on Netlify docs。

手动配置

或者，如果你更喜欢手动配置，可以在项目根目录添加一个 netlify.toml 文件：

[build]
  command = "vite build"
  publish = "dist/client"
[dev]
  command = "vite dev"
  port = 3000

或者直接在 Netlify 应用中设置上述配置。

其他部署方式

Netlify 还支持其他部署方式，比如从 GitHub、GitLab 等托管的 git 仓库持续部署、从模板开始、从 AI 代码生成工具部署或导入以及更多。

Railway ⭐ 官方合作伙伴

Railway

Railway 提供零配置的即时部署。先按照下面的 Nitro 部署说明操作，再部署到 Railway：

把你的代码推送到一个 GitHub 仓库
在 railway.com 把你的仓库连接到 Railway
Railway 会自动检测你的构建设置并部署你的应用

Railway 自动提供：

自动部署：每次推送代码到仓库时
内置数据库（Postgres、MySQL、Redis、MongoDB）
拉取请求的预览环境
自动 HTTPS 和自定义域名

更多细节见 Railway 的文档。

Nitro

Nitro 是一个与平台无关的层，让你能把 TanStack Start 应用部署到各种各样的托管平台。

⚠️ nitro/vite 插件原生与 Vite Environments API 集成，作为 TanStack Start 的底层构建工具。它仍处于积极开发中，并定期更新。请把你遇到的所有问题连同一个可复现示例一起提交，以便调查。

安装 nitro：

npm install nitro

把 nitro/vite 插件添加到你的 vite.config.ts 文件：

import { tanstackStart } from '@tanstack/react-start/plugin/vite'
import { defineConfig } from 'vite'
import { nitro } from 'nitro/vite'
import viteReact from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [tanstackStart(), nitro(), viteReact()],
})

性能提示：FastResponse

如果你用 Nitro 部署到 Node.js（底层使用 srvx），可以把全局 Response 构造函数替换成 srvx 优化的 FastResponse，获得约 5% 的吞吐量提升。

首先安装 srvx：

npm install srvx

然后把它添加到你的服务器入口点（src/server.ts）：

import { FastResponse } from 'srvx'
globalThis.Response = FastResponse

这是因为 srvx 的 FastResponse 包含一个优化的 _toNodeResponse() 路径，避免了标准 Web Response 到 Node.js 转换的开销。这个优化只适用于使用 Nitro/h3/srvx 的 Node.js 部署。

Vercel

按照上面的 Nitro 部署说明操作。用一键部署流程把你的应用部署到 Vercel，然后就大功告成了！

Node.js / Docker

使用与你构建工具匹配的 Node.js 部署形态。

按照上面的 Nitro 部署说明操作。用 node 命令从构建产物文件启动你的应用。

确保 package.json 中有 build 和 start 两个 npm 脚本：

    "build": "vite build",
    "start": "node .output/server/index.mjs"

然后你可以运行下面的命令构建应用：

npm run build

运行下面的命令启动应用：

npm run start

Bun

重要

目前，Bun 专属的部署指南只适用于 React 19。如果你在使用 React 18，请参考上面的 Node.js 部署指南。

确保 package.json 中你的 react 和 react-dom 包版本是 19.0.0 或更高。如果不是，运行下面的命令升级：

bun install react@19 react-dom@19

对于 Vite 构建，按照上面的 Nitro 部署说明操作。根据你调用构建的方式，你可能需要在 Nitro 配置中设置 'bun' preset：

// vite.config.ts
import { tanstackStart } from '@tanstack/react-start/plugin/vite'
import { defineConfig } from 'vite'
import { nitro } from 'nitro/vite'
import viteReact from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [tanstackStart(), nitro({ preset: 'bun' }), viteReact()],
})

用 Bun 搭建生产服务器

或者，你可以用自定义服务器实现，利用 Bun 的原生 API。

我们提供了一个参考实现，展示构建生产级 Bun 服务器的一种方法。这个示例使用 Bun 原生函数以获得最佳性能，并包含智能资源预加载和内存管理等特性。

这是一个起点——你可以按需调整，或为你的用例简化它。

这个示例演示了什么：

用 Bun 的原生文件处理提供静态资源
混合加载策略（预加载小文件，按需提供大文件）
ETag 支持和 Gzip 压缩等可选特性
生产级的缓存头

快速设置：

把示例仓库中的 server.ts 文件复制到你的项目根目录（或把它作为你实现灵感的来源）
构建你的应用：
```
bun run build
```
启动服务器：
```
bun run server.ts
```

配置（可选）：

参考服务器实现包含几个通过环境变量控制的可选配置项。你可以原样使用它们、修改它们，或移除不需要的特性：

# Basic usage - just works out of the box
bun run server.ts

# Common configurations
PORT=8080 bun run server.ts  # Custom port
ASSET_PRELOAD_VERBOSE_LOGGING=true bun run server.ts  # See what's happening

可用的环境变量：

变量	说明	默认值
`PORT`	服务器端口	`3000`
`ASSET_PRELOAD_MAX_SIZE`	预加载进内存的最大文件大小（字节）	`5242880`（5MB）
`ASSET_PRELOAD_INCLUDE_PATTERNS`	逗号分隔的包含文件 glob 模式	所有文件
`ASSET_PRELOAD_EXCLUDE_PATTERNS`	逗号分隔的排除文件 glob 模式	无
`ASSET_PRELOAD_VERBOSE_LOGGING`	启用详细日志	`false`
`ASSET_PRELOAD_ENABLE_ETAG`	启用 ETag 生成	`true`
`ASSET_PRELOAD_ENABLE_GZIP`	启用 Gzip 压缩	`true`
`ASSET_PRELOAD_GZIP_MIN_SIZE`	Gzip 的最小文件大小（字节）	`1024`（1KB）
`ASSET_PRELOAD_GZIP_MIME_TYPES`	可参与 Gzip 的 MIME 类型	`text/,application/javascript,application/json,application/xml,image/svg+xml`

高级配置示例

# Optimize for minimal memory usage
ASSET_PRELOAD_MAX_SIZE=1048576 bun run server.ts

# Preload only critical assets
ASSET_PRELOAD_INCLUDE_PATTERNS="*.js,*.css" \
ASSET_PRELOAD_EXCLUDE_PATTERNS="*.map,vendor-*" \
bun run server.ts

# Disable optional features
ASSET_PRELOAD_ENABLE_ETAG=false \
ASSET_PRELOAD_ENABLE_GZIP=false \
bun run server.ts

# Custom Gzip configuration
ASSET_PRELOAD_GZIP_MIN_SIZE=2048 \
ASSET_PRELOAD_GZIP_MIME_TYPES="text/,application/javascript,application/json" \
bun run server.ts

示例输出：

📦 Loading static assets from ./dist/client...
   Max preload size: 5.00 MB

📁 Preloaded into memory:
   /assets/index-a1b2c3d4.js           45.23 kB │ gzip:  15.83 kB
   /assets/index-e5f6g7h8.css           12.45 kB │ gzip:   4.36 kB

💾 Served on-demand:
   /assets/vendor-i9j0k1l2.js          245.67 kB │ gzip:  86.98 kB

✅ Preloaded 2 files (57.68 KB) into memory
🚀 Server running at http://localhost:3000

完整可运行的示例请看本仓库的 TanStack Start + Bun example。

Appwrite Sites

部署到 Appwrite Sites 时，你需要完成几个步骤：

创建一个 TanStack Start 应用（或使用现有的）

npx @tanstack/cli@latest create

把你的项目推送到 GitHub 仓库

创建一个 GitHub 仓库并推送你的代码。

创建一个 Appwrite 项目

前往 Appwrite Cloud 注册（如果还没注册），然后创建你的第一个项目。

部署你的站点

在你的 Appwrite 项目中，从侧边栏进入 Sites 页面。点击 Create site，选择 Connect a repository，连接你的 GitHub 账户并选择你的仓库。

选择生产分支和根目录
确认 TanStack Start 被选为框架
确认构建设置：
- 安装命令： npm install
- 构建命令： npm run build
- 输出目录： ./dist（如果你使用 Nitro v2 或 v3，应该是 ./.output）
添加任何必需的环境变量
点击 Deploy

部署成功后，点击 Visit site 按钮查看你部署的应用。

托管与部署

On this page