跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

部署现有项目

最后更新 查看 MarkdownAgent 设置

Wrangler 可以自动检测你的框架,并为 Cloudflare Workers 配置项目。这样你只需一条命令即可部署现有项目,无需手动创建配置文件或安装适配器。

工作原理

当项目目录中没有 Wrangler 配置文件时,运行 wrangler deploy 或 wrangler setup,Wrangler 将:

  1. 检测你的框架 — 分析项目以识别你使用的框架
  2. 提示确认 — 显示检测到的设置,并在修改前请求你确认
  3. 安装适配器 — 为你的框架安装所需的 Cloudflare 适配器
  4. 生成配置 — 创建包含合适设置的 wrangler.jsonc 文件
  5. 更新 package.json — 添加 deploy、preview、cf-typegen 等实用脚本
  6. 配置 git — 向 .gitignore 添加 Wrangler 相关条目

支持的框架

自动配置支持以下框架:

框架 适配器/工具 说明
Next.js vinext 为 Cloudflare Workers 配置 vinext,并添加所需的 Vite 和 Wrangler 配置。
Astro @astrojs/cloudflare 自动运行 astro add cloudflare
SvelteKit @sveltejs/adapter-cloudflare 自动运行 sv add sveltekit-adapter
Nuxt 内置 Cloudflare 预设
React Router Cloudflare Vite 插件
Solid Start 内置 Cloudflare 预设
TanStack Start Cloudflare Vite 插件
Angular
Analog 内置 Cloudflare 预设
Vite Cloudflare Vite 插件
Vike
Waku
静态站点 无 任何包含 index.html 的目录

自动配置也可能适用于其他项目,例如 React 或 Vue SPA。尝试运行 wrangler deploy 或 wrangler setup,查看是否能检测到你的项目。

创建和修改的文件

自动配置运行时,可能会创建或修改以下文件:

wrangler.jsonc

会创建新的 Wrangler 配置文件,其中包含适合你所用框架的设置:

{
    "$schema": "node_modules/wrangler/config-schema.json",
    "name": "my-project",
    "main": "dist/_worker.js/index.js",
    "upload_source_maps": true,
    // Set this to today's date
    "compatibility_date": "2026-11-20",
    "compatibility_flags": ["nodejs_compat"],
    "assets": {
        "binding": "ASSETS",
        "directory": "dist",
    },
    "observability": {
        "enabled": true,
    },
}
"$schema" = "node_modules/wrangler/config-schema.json"
name = "my-project"
main = "dist/_worker.js/index.js"
upload_source_maps = true
# Set this to today's date
compatibility_date = "2026-11-20"
compatibility_flags = [ "nodejs_compat" ]

[assets]
binding = "ASSETS"
directory = "dist"

[observability]
enabled = true

具体配置会因框架而异。

package.json

会向 package.json 添加新脚本:

{
    "scripts": {
        "deploy": "npm run build && wrangler deploy",
        "preview": "npm run build && wrangler dev",
        "cf-typegen": "wrangler types"
    }
}

.gitignore

会添加 Wrangler 相关条目:

# wrangler files
.wrangler
.dev.vars*
!.dev.vars.example

.assetsignore

对于在输出目录中生成 Worker 文件的框架,会创建 .assetsignore 文件,以在静态资源上传时排除这些文件:

_worker.js
_routes.json

使用自动配置

通过自动配置部署

如需部署现有项目,请在项目目录中运行 wrangler deploy:

npx wrangler deploy

Wrangler 会检测你的框架,显示将要应用的配置,并在修改并部署前提示你确认。

仅配置、不部署

如需配置项目但不部署,请使用 wrangler setup:

npx wrangler setup

当你想在部署前查看生成的配置时,这很有用。

使用 dry run 预览变更

要查看将进行的更改,而不实际修改任何文件:

npx wrangler setup --dry-run

这会输出将要生成的配置摘要。

跳过配置确认

如需应用检测到的配置而不进行确认,请向 wrangler setup传入 --yes:

npx wrangler setup --yes

此选项适用于 CI/CD 环境,也适用于你希望接受检测到的设置而不检查的情况。

设置完成后,Wrangler 会显示用于部署的命令。对于包含 package.json 的项目,请使用生成的 deploy 脚本:

npm run deploy

如果 Wrangler 检测到构建命令,生成的脚本会先运行该命令,然后部署项目。对于不含 package.json 的项目,请运行 wrangler deploy。

从仪表板导入仓库

通过 Cloudflare 仪表板导入 GitHub 或 GitLab 仓库时,autoconfig 会以非交互方式运行。若仓库中没有 Wrangler 配置文件,Workers Builds 会创建包含必要配置的拉取请求。

该 PR 包含上文所述的全部配置更改。会生成预览部署,以便你在合并前测试更改。合并后,项目即可部署。

更多详情,请参阅自动拉取请求。

跳过自动配置

若不希望运行自动配置,请在运行 wrangler deploy 前确保项目中已有有效的 Wrangler 配置文件(wrangler.toml、wrangler.json 或 wrangler.jsonc)。

你也可以按照框架指南中的框架专项指南手动配置项目。

Next.js 配置

对于 Next.js 项目,自动配置使用 vinext 作为 Cloudflare Workers 的默认部署路径。生成的配置会添加 vinext 和 Vite 依赖、创建 Cloudflare Workers 配置,并添加用于开发、构建和部署的 package 脚本。

vinext 支持 Incremental Static Regeneration(ISR)、"use cache" 和 unstable_cache 等 Next.js 缓存功能。对于生产应用程序,请为生成的 Workers 项目配置应用程序所需的缓存后端。更多信息请参阅 vinext caching ↗。

如果需要使用 OpenNext 适配器而不是 vinext,请按照 OpenNext 适配器指南手动配置。

故障排除

检测到多个框架

通过 Cloudflare 仪表板中的 Workers Builds 导入仓库时,若项目包含多个框架,自动配置会失败。要解决此问题,请将根目录设置为仅包含一个框架的路径。对于 monorepo,请参阅 monorepo 设置。

在本地运行 wrangler deploy 或 wrangler setup 时,若检测到多个框架,Wrangler 会提示你选择要使用的框架。

未检测到框架

若未检测到你的框架,请确保 package.json 中将该框架列为依赖项。

配置已存在

若已存在 Wrangler 配置文件,则不会运行自动配置。要重新配置项目,请删除现有配置文件,然后再次运行 wrangler deploy 或 wrangler setup。

工作区

目前对 monorepo 以及 npm/yarn/pnpm workspaces 的支持有限。Wrangler 会分析你运行命令的项目目录,但不会检测安装在 workspace 根目录的依赖项。若框架作为依赖项列在 workspace 根目录的 package.json 中,而非单个项目的 package.json 中,可能导致框架检测失败。

若遇到问题,请在 Wrangler GitHub 仓库 ↗中反馈。

这篇文档对您有帮助吗?