部署现有项目

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 相关条目

自动配置支持以下框架：

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

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

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

{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "my-project",
	"main": "dist/_worker.js/index.js",
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"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"
# Set this to today's date
compatibility_date = "2026-08-17"
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 deploy

yarn wrangler deploy

pnpm wrangler deploy

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

若要在不部署的情况下配置项目，请使用 wrangler setup：

npx wrangler setup

yarn wrangler setup

pnpm wrangler setup

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

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

npx wrangler setup --dry-run

yarn wrangler setup --dry-run

pnpm wrangler setup --dry-run

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

要跳过确认提示，请使用 --yes 标志：

npx wrangler deploy --yes

yarn wrangler deploy --yes

pnpm wrangler deploy --yes

这会使用合理的默认值自动应用配置。在 CI/CD 环境中，或当你希望直接接受检测到的设置时，这很有用。

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

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

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

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

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

对于 Next.js 项目，若你的 Cloudflare 账户已启用 R2，自动配置会为缓存设置 R2。R2 缓存可提升 Incremental Static Regeneration (ISR) ↗ 及其他 Next.js 缓存功能的性能。

• 若账户已启用 R2：自动配置会创建 R2 存储桶并自动配置缓存。
• 若未启用 R2：项目会在无缓存的情况下完成配置。你可以稍后启用 R2，并按照 OpenNext 缓存文档 ↗手动配置缓存。

要检查 R2 是否已启用或进行启用，请前往 Cloudflare 仪表板 ↗中的 Storage & Databases > R2。

通过 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 仓库 ↗中反馈。