HGfast Cloud 灵狐加速 · 一站式全球云网络返回首页

Cloudflare Workers 怎么部署?CLI、控制台、域名与报错速查

更新于 2026-11-15 · hgfastapp.lol

简答: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 --device

Wrangler通用命令文档说明,--device使用设备授权流程,不启动本地回调服务器;如需手动复制验证地址,可加--browser=false,详见Wrangler通用命令文档。

先选路径:纯Worker、静态网站、Git项目怎么部署

Cloudflare Workers部署方式取决于你手里的项目形态。不要把静态网站、API和已有Git仓库都套用同一套配置。

项目情况建议路径关键命令或入口部署后入口
新建API、Webhook或边缘脚本Wrangler CLInpm create cloudflare@latestworkers.dev或Custom Domain
只想在浏览器快速创建模板Cloudflare控制台Workers & Pages > Create application控制台提供的预览地址
静态网站或前端加APIWorkers Static Assetsassets.directory指向构建目录workers.dev、Custom Domain或Route
已有Git仓库Workers BuildsBuild command加npx wrangler deploy生产部署或Preview
Worker就是域名源站Custom DomainDomains或Domains & Routes中添加整个主机名由Worker处理
已有源站前增加处理逻辑Routeroutes配置匹配规则匹配路径先经过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
  1. 运行npm create cloudflare@latest -- my-first-worker创建项目。
  2. 按提示选择Worker或适合项目的模板,并进入项目目录。
  3. 打开生成的入口文件,修改返回内容或接口逻辑。
  4. 运行npx wrangler login完成账户授权。
  5. 运行npx wrangler dev启动本地开发,再访问终端显示的本地地址。
  6. 确认本地响应正确后,运行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 commandnpx wrangler deploynpx wrangler deploy确认命令在Root directory中可执行
Preview commandnpx wrangler previewnpx 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-run

Windows PowerShell可使用:

Get-Location
Get-ChildItem
Get-Content package.json
npx wrangler deploy --dry-run

Preview构建没有地址时,优先检查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 rollback

Cloudflare回滚文档说明,回滚会创建一个指向所选版本的新部署,并将流量切换到该版本;但KV、D1、R2或Durable Objects等资源结构发生变化时,旧版本不一定能够安全回滚,具体限制见Workers回滚文档。

常见部署错误:按现象分流处理

下面把常见问题分成“错误”和“可改进”两类。修正栏给出同一句的改法,方便直接执行。

类别错误或现象常见检查点修正
错误command not found: nodeNode.js未安装或PATH未刷新安装Node.js并重新打开终端,再运行node --version
错误Not logged inOAuth回调不可达或设备授权未完成运行npx wrangler login --device并按终端提示授权
错误静态资源404构建目录和assets.directory不一致先运行npm run build,再把配置改为实际输出目录
错误ERR_NAME_NOT_RESOLVEDRoute主机名缺少DNS记录添加并代理对应DNS记录,或改用Custom Domain
错误访问出现523Route后的源站不可达,或入口类型选择不匹配核对DNS、源站可达性和Worker是否应作为Custom Domain源站
可改进本地正常、线上异常环境变量、绑定、构建产物或生产域名不同分别核对Production和Preview变量、绑定及构建目录
可改进部署成功但没有Preview URLPreview主机未启用或命令未报告地址启用Preview主机,并确认使用npx wrangler preview
可改进回滚后仍报错旧代码依赖已修改或删除的资源先检查KV、D1、R2、队列和Durable Objects的资源状态

Windows PowerShell核验命令:

node --version
npm --version
Resolve-DnsName example.com
curl.exe -I https://example.com

macOS和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等资源。

相关阅读

参考资料

  1. Cloudflare Workers CLI入门文档
  2. Wrangler通用命令文档
  3. Wrangler配置文档
  4. Cloudflare Routes and domains官方说明
  5. Workers Sites迁移说明
  6. Workers Static Assets入门文档
  7. Static Assets配置文档
  8. Workers Builds配置文档
  9. Workers Builds排错文档
  10. workers.dev配置文档
  11. Workers Routes文档
  12. Workers实时日志文档