Wrangler 可以自动检测你的框架,并为 Cloudflare Workers 配置项目。这样你只需一条命令即可部署现有项目,无需手动创建配置文件或安装适配器。
当项目目录中没有 Wrangler 配置文件时,运行 wrangler deploy 或 wrangler setup,Wrangler 将:
- 检测你的框架 — 分析项目以识别你使用的框架
- 提示确认 — 显示检测到的设置,并在修改前请求你确认
- 安装适配器 — 为你的框架安装所需的 Cloudflare 适配器
- 生成配置 — 创建包含合适设置的
wrangler.jsonc文件 - 更新 package.json — 添加
deploy、preview、cf-typegen等实用脚本 - 配置 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 配置文件,其中包含适合你所用框架的设置:
{
"$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 添加新脚本:
{
"scripts": {
"deploy": "npm run build && wrangler deploy",
"preview": "npm run build && wrangler dev",
"cf-typegen": "wrangler types"
}
}会添加 Wrangler 相关条目:
# wrangler files
.wrangler
.dev.vars*
!.dev.vars.example对于在输出目录中生成 Worker 文件的框架,会创建 .assetsignore 文件,以在静态资源上传时排除这些文件:
_worker.js
_routes.json如需部署现有项目,请在项目目录中运行 wrangler deploy:
npx wrangler deployyarn wrangler deploypnpm wrangler deployWrangler 会检测你的框架,显示将要应用的配置,并在修改并部署前提示你确认。
如需配置项目但不部署,请使用 wrangler setup:
npx wrangler setupyarn wrangler setuppnpm wrangler setup当你想在部署前查看生成的配置时,这很有用。
要查看将进行的更改,而不实际修改任何文件:
npx wrangler setup --dry-runyarn wrangler setup --dry-runpnpm wrangler setup --dry-run这会输出将要生成的配置摘要。
如需应用检测到的配置而不进行确认,请向 wrangler setup传入 --yes:
npx wrangler setup --yesyarn wrangler setup --yespnpm wrangler setup --yes此选项适用于 CI/CD 环境,也适用于你希望接受检测到的设置而不检查的情况。
设置完成后,Wrangler 会显示用于部署的命令。对于包含 package.json 的项目,请使用生成的 deploy 脚本:
npm run deployyarn run deploypnpm 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 项目,自动配置使用 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 仓库 ↗中反馈。