Cloudflare Workers 怎么部署?CLI、控制台、域名与报错速查
简答:Cloudflare Workers部署先选CLI、控制台或Git路径:新手可用6条命令创建并发布,静态网站配置Static Assets,先用workers.dev验证,再按源站关系选择Custom Domain或Route,最后查看日志并保留回滚版本。
定义:Cloudflare Workers部署,是将Worker脚本或包含静态资源的项目发布到Cloudflare,并通过workers.dev、自定义域名或Route接收请求。
先看30秒速查卡:6条命令完成首次部署
如果你已经有Cloudflare账户和一台安装Node.js的电脑,可以先按下面顺序操作。命令适用于Windows PowerShell、macOS和Linux终端;项目创建过程中仍需按提示选择模板和目录。
node --version
npm --version
npm create cloudflare@latest -- my-first-worker
cd my-first-worker
npx wrangler login
npx wrangler dev
npx wrangler deploy
curl -i https://你的Worker名称.你的账户子域名.workers.dev/官方CLI入门文档把Cloudflare账户、Node.js、C3创建项目、Wrangler本地开发和部署列为主要流程,创建命令可参考Cloudflare Workers CLI入门文档。Windows如果系统中的curl行为不同,可以使用:
curl.exe -i https://你的Worker名称.你的账户子域名.workers.dev/如果你在远程服务器、容器或没有本地回调端口的环境中登录,使用:
npx wrangler login --deviceWrangler通用命令文档说明,--device使用设备授权流程,不启动本地回调服务器;如需手动复制验证地址,可加--browser=false,详见Wrangler通用命令文档。
先选路径:纯Worker、静态网站、Git项目怎么部署
Cloudflare Workers部署方式取决于你手里的项目形态。不要把静态网站、API和已有Git仓库都套用同一套配置。
| 项目情况 | 建议路径 | 关键命令或入口 | 部署后入口 |
|---|---|---|---|
| 新建API、Webhook或边缘脚本 | Wrangler CLI | npm create cloudflare@latest | workers.dev或Custom Domain |
| 只想在浏览器快速创建模板 | Cloudflare控制台 | Workers & Pages > Create application | 控制台提供的预览地址 |
| 静态网站或前端加API | Workers Static Assets | assets.directory指向构建目录 | workers.dev、Custom Domain或Route |
| 已有Git仓库 | Workers Builds | Build command加npx wrangler deploy | 生产部署或Preview |
| Worker就是域名源站 | Custom Domain | Domains或Domains & Routes中添加 | 整个主机名由Worker处理 |
| 已有源站前增加处理逻辑 | Route | routes配置匹配规则 | 匹配路径先经过Worker |
官方对Routes、Custom Domains和workers.dev的区分是:Custom Domain适合Worker作为应用源站,Route适合已有外部源站前的代理处理,workers.dev适合快速开始和非关键业务验证。可查看Routes and domains官方说明。
结论框:新手先用workers.dev验证;Worker本身是域名源站时选Custom Domain;已有源站时选Route;静态网站新项目优先使用Workers Static Assets。
用Wrangler从零创建Worker并发布
Wrangler适合需要本地开发、代码版本管理和重复部署的项目。开始前先检查Node.js和npm是否在PATH中:
node --version
npm --version- 运行
npm create cloudflare@latest -- my-first-worker创建项目。 - 按提示选择Worker或适合项目的模板,并进入项目目录。
- 打开生成的入口文件,修改返回内容或接口逻辑。
- 运行
npx wrangler login完成账户授权。 - 运行
npx wrangler dev启动本地开发,再访问终端显示的本地地址。 - 确认本地响应正确后,运行
npx wrangler deploy发布。
部署后不要只看命令是否退出成功,还应复制输出的Worker地址进行HTTP验证:
# macOS / Linux
curl -i https://你的Worker地址/
# Windows PowerShell
curl.exe -i https://你的Worker地址/如果项目目录没有Wrangler配置文件,官方命令文档说明wrangler deploy可能尝试检测框架并生成项目配置;新项目建议使用wrangler.jsonc作为配置文件,相关说明见Wrangler配置文档。
静态网站和前端加API:用Static Assets配置目录
旧教程中常见的Workers Sites使用site.bucket配置。Cloudflare文档已经说明,Workers Sites在Wrangler v4中已弃用,新项目应改用Workers Static Assets;已有项目需要把静态资源目录迁移到assets.directory,而不是继续照搬旧的site配置。可参考Workers Sites迁移说明。
一个脱敏的wrangler.jsonc示例:
{
"$schema": "./node_modules/wrangler/config-schema.json",
"name": "my-static-site",
"main": "src/index.js",
"compatibility_date": "YYYY-MM-DD",
"assets": {
"directory": "./dist"
}
}name:Worker名称,会影响workers.dev地址和项目识别。main:Worker入口文件;是否需要该字段取决于项目结构。compatibility_date:运行时兼容日期,应按当前项目实际维护,不要直接复制旧文章日期。assets.directory:构建后的静态文件目录,常见为dist、build或public。
典型流程如下:
npm install
npm run build
npx wrangler dev
npx wrangler deploy如果部署后首页返回404,先执行构建命令,再检查assets.directory是否指向实际生成目录。静态资源配置和绑定方式可继续查看Workers Static Assets入门文档和Static Assets配置文档。
控制台和Git部署:构建目录、Preview命令怎么填
不想在本地创建项目时,可以进入Workers & Pages,选择Create application,再选择模板或连接Git仓库。已有仓库的重点不是“连接成功”,而是根目录、构建命令和部署命令必须与项目文件位置一致。
| 配置项 | 纯Worker示例 | 前端或静态网站示例 | 核对点 |
|---|---|---|---|
| Root directory | / | apps/web | 该目录应包含package.json和Wrangler配置 |
| Build command | 按项目需要或留空 | npm run build | 构建后目录要与assets.directory一致 |
| Deploy command | npx wrangler deploy | npx wrangler deploy | 确认命令在Root directory中可执行 |
| Preview command | npx wrangler preview | npx wrangler preview | 需要Preview时使用支持该流程的Wrangler版本 |
Workers Builds配置文档显示,Deploy command默认是npx wrangler deploy,Preview command默认是npx wrangler preview;Preview设置可按环境增加变量、密钥和绑定,详见Workers Builds配置文档。
如果仓库是单仓库多项目,先填写具体Root directory,再在该目录内检查:
pwd
ls
cat package.json
npx wrangler deploy --dry-runWindows PowerShell可使用:
Get-Location
Get-ChildItem
Get-Content package.json
npx wrangler deploy --dry-runPreview构建没有地址时,优先检查Preview主机是否启用,以及Preview command是否输出了可识别的Preview URL。官方排错文档列出了Preview主机和命令版本要求,可参考Workers Builds排错文档。
workers.dev、Custom Domain和Route:配置示例与选择顺序
首次部署建议先用workers.dev验证代码。Workers账户可以配置账户子域名,Worker地址通常由Worker名称和账户子域名组成。控制台检查路径是Workers & Pages > 选择Worker > Domains或Settings > Domains & Routes,具体界面可能随账户版本变化。
如果workers.dev没有访问地址,先检查账户子域名是否已配置,以及该Worker的workers.dev路由是否被禁用。官方文档说明,workers.dev可在控制台的Workers & Pages页面修改账户子域名;若在配置中设置workers_dev: false,重新部署后会关闭该入口,详情见workers.dev配置文档。
Worker是域名源站时,可在配置中使用Custom Domain:
{
"routes": [
{
"pattern": "api.example.com",
"custom_domain": true
}
]
}已有源站时使用Route:
{
"routes": [
{
"pattern": "api.example.com/*",
"zone_name": "example.com"
}
]
}Route要求对应域名或子域名存在可代理的DNS记录;如果没有DNS记录,访问可能出现ERR_NAME_NOT_RESOLVED。Route配置示例和DNS前提可查看Workers Routes文档。
假如自定义域名访问出现523,先判断该入口是Route还是Custom Domain:Route通常位于已有源站之前,需要确认源站DNS和可达性;如果Worker本身就是应用源站,应检查是否应改用Custom Domain。这里是按官方路由模型给出的排查方向,不代表所有523都由同一原因造成。
部署后看日志、保留版本并按需回滚
部署闭环至少包括公开地址验证、日志检查和版本留存。先访问workers.dev或自定义域名,再查看Worker是否收到请求和是否抛出异常。
实时日志可以在项目目录运行:
npx wrangler tail官方实时日志文档说明,wrangler tail会在终端显示收到请求时的结构化日志,包括请求、异常和自定义日志;也可以在控制台进入Worker的Observability查看日志,参见Workers实时日志文档。如果要启用Workers Logs,可在配置中加入:
{
"observability": {
"enabled": true,
"head_sampling_rate": 1
}
}部署前后建议把代码和wrangler.jsonc提交到Git,并记录本次部署对应的提交。发现新版本异常时,可以在控制台进入Workers & Pages > Worker > Deployments,选择目标版本并执行Rollback,也可以使用:
npx wrangler rollbackCloudflare回滚文档说明,回滚会创建一个指向所选版本的新部署,并将流量切换到该版本;但KV、D1、R2或Durable Objects等资源结构发生变化时,旧版本不一定能够安全回滚,具体限制见Workers回滚文档。
常见部署错误:按现象分流处理
下面把常见问题分成“错误”和“可改进”两类。修正栏给出同一句的改法,方便直接执行。
| 类别 | 错误或现象 | 常见检查点 | 修正 |
|---|---|---|---|
| 错误 | command not found: node | Node.js未安装或PATH未刷新 | 安装Node.js并重新打开终端,再运行node --version |
| 错误 | Not logged in | OAuth回调不可达或设备授权未完成 | 运行npx wrangler login --device并按终端提示授权 |
| 错误 | 静态资源404 | 构建目录和assets.directory不一致 | 先运行npm run build,再把配置改为实际输出目录 |
| 错误 | ERR_NAME_NOT_RESOLVED | Route主机名缺少DNS记录 | 添加并代理对应DNS记录,或改用Custom Domain |
| 错误 | 访问出现523 | Route后的源站不可达,或入口类型选择不匹配 | 核对DNS、源站可达性和Worker是否应作为Custom Domain源站 |
| 可改进 | 本地正常、线上异常 | 环境变量、绑定、构建产物或生产域名不同 | 分别核对Production和Preview变量、绑定及构建目录 |
| 可改进 | 部署成功但没有Preview URL | Preview主机未启用或命令未报告地址 | 启用Preview主机,并确认使用npx wrangler preview |
| 可改进 | 回滚后仍报错 | 旧代码依赖已修改或删除的资源 | 先检查KV、D1、R2、队列和Durable Objects的资源状态 |
Windows PowerShell核验命令:
node --version
npm --version
Resolve-DnsName example.com
curl.exe -I https://example.commacOS和Linux核验命令:
node --version
npm --version
dig example.com
curl -I https://example.com排查顺序建议保持为:项目目录和依赖、构建输出、Wrangler配置、公开地址、域名路由、日志和资源绑定。这样能避免在尚未确认入口类型前反复修改DNS。
常见问题
Cloudflare Workers部署一定要安装Node.js吗?
使用Wrangler CLI或C3创建、开发和部署项目时,通常需要Node.js。只在控制台创建简单Worker可以先不配置本地环境,但后续使用本地命令或Git构建时仍需按官方环境要求准备运行环境。
Cloudflare Workers和Pages应该怎么选?
新建Worker脚本、边缘逻辑或前端加Worker接口时,可优先评估Workers和Workers Static Assets;已有Pages项目或继续使用既有Pages Git流程时,可以保留Pages。最终应按项目结构和构建方式选择。
为什么部署成功后workers.dev打不开?
先确认账户子域名已配置、Worker名称和访问地址一致,并检查该Worker是否关闭了workers.dev路由。再用curl访问根路径并运行npx wrangler tail查看请求是否到达。
静态网站部署后显示404怎么办?
先执行构建命令,确认实际生成的是dist、build还是public,再让wrangler.jsonc中的assets.directory指向该目录。不要把源码目录直接当成静态资源目录。
Route和Custom Domain有什么区别?
Custom Domain适合Worker作为应用源站,让整个主机名由Worker处理;Route适合已有源站前的路径或主机名匹配,并要求对应域名存在可代理DNS记录。
Workers Builds里的Preview command应该填什么?
官方配置文档显示,Preview command默认是npx wrangler preview。若使用自定义命令,应确认项目依赖的Wrangler版本支持Preview,并检查命令是否向Workers Builds报告Preview URL。
Cloudflare Workers可以回滚到旧版本吗?
可以通过控制台Deployments中的Rollback或npx wrangler rollback回滚到先前版本,但资源绑定和数据结构发生变化时,旧代码可能无法直接兼容,回滚前应检查KV、D1、R2和Durable Objects等资源。