Wrangler 这个词丢进搜索框会撞出好几拨完全不相干的结果一款方头方脑的硬派越野车、一个做牛仔服饰的老牌子还有一大片出现在开发者社区里的终端截图。如果你是在翻文档、看部署日志的时候碰到它的那大概率指的是第三样——Cloudflare 官方出品的 Workers 命令行工具。它本身不写业务逻辑也不管你的界面好不好看它只负责一件事把本地这份代码用可复现、可回滚、可进代码仓库的方式推到边缘节点上跑起来。我前后用它带过几个小项目从最早的wrangler publish时代一路用到现在的wrangler deploy中间踩过的坑不算少。这篇就当成一次完整的项目复盘来写它到底解决什么问题、配置文件里哪几个字段必须动、本地调试和线上调试差在哪、KV/D1/R2 这些存储怎么接、部署翻车了怎么回滚以及它在什么场景下其实不适合用。刚接触 serverless 的同学可以照着顺序抄一遍已经用过几次但总在报错里打转的可以直接跳到第四节的排查表。1. Wrangler 到底是什么先把它解决的问题说清楚1.1 一句话定义以及三个最常见的误解Wrangler 是 Cloudflare 官方维护的命令行工具服务于 Workers 这套运行时的开发与部署全流程。我更喜欢把它理解成「脚手架 打包器 部署器」三合一create帮你在空目录里搭出骨架dev在本地起一个模拟运行时并把你的代码打进去deploy把打包产物连同配置一起上传。整个过程不需要你手动开控制台点按钮。围绕它的误解主要有三个。第一个是把它当成框架——不是的它完全不侵入代码结构你的入口文件就是普通的 JavaScript 或 TypeScriptexport default { fetch }这样导出就行换成别的构建工具照样能跑Wrangler 只是负责把它送上云。第二个是觉得必须全局安装——我早期也是npm i -g wrangler结果同时维护三个项目时版本互相打架命令参数都不一样。后来改成每个项目里npm i -D wrangler用npx wrangler调用问题立刻消失。第三个是以为wrangler dev起来的就是「线上环境」——默认情况下它跑的是本地模拟运行时数据是隔离的很多行为跟真实边缘节点并不完全一致这点后面会专门讲。把这三个误解捋顺后面看配置和报错就顺多了。1.2 为什么不用控制台点鼠标核心价值是可复现控制台上点几下也能上线一个 Worker。那为什么还要折腾命令行答案不在「快」而在「可复现」。Worker 上线需要一堆参数入口脚本、兼容性日期、环境变量、绑定关系、路由规则、自定义域名。这些如果只存在控制台里就会带来一连串麻烦改了什么没人能 diff、出问题回不到上一版、新人接手只能靠截图和口口相传。而 Wrangler 把这些全部收进一个wrangler.toml或wrangler.jsonc里这个文件跟着代码进 Git 仓库谁都能看到「现在线上到底是什么配置」。我遇到过最典型的一次事故某个同事在控制台手动加了一个 KV 绑定本地配置文件里没同步。两周后另一个人重新部署线上的绑定被覆盖掉接口直接 500。排查了快一小时才发现是「配置漂移」。从那以后我们定了规矩——所有跟 Worker 相关的改动必须走配置文件 Pull Request控制台只用来查看和应急处置。这就是 Wrangler 最实在的价值把「线上状态」变成一份可以被审阅的文本。1.3 它的边界在哪里别指望它包办一切用久了会形成一种错觉觉得 Wrangler 什么都能干。实际上它的边界挺清晰的。它不负责数据库的结构演进——D1 的建表和变更要靠wrangler d1 migrations配合 SQL 文件来做版本管理还得你自己盯。它不负责前端框架的构建——TypeScript 转译、CSS 处理、代码分割这些交给 Vite、esbuild 之类的工具Wrangler 只处理最后一步打包和上传。它也不能替你在线上做断点调试——wrangler tail能看实时日志但想看变量快照还是得靠本地复现加上日志打点。另外一点要有心理预期本地模拟和线上真机之间一定存在差异。本地用的是受限的执行环境某些 API 是模拟实现边界的网络行为、超时表现都不一样。我的习惯是本地跑通之后先用一个测试域名部署一版用wrangler tail观察真实流量下的表现确认没问题再切正式路由。这个「两段式上线」的习惯帮我拦下过好几次本地完全看不出来的问题。2. 核心概念拆解配置文件、绑定与运行环境2.1 wrangler.toml 里必须搞懂的字段配置文件是整套流程的中枢。字段看着多真正每次都要打交道的其实就是下面这几个。字段作用我的实操经验nameWorker 名称决定默认域名前缀改名字等于新建一个 Worker别随手改main入口文件路径写错会报模块找不到路径相对项目根目录compatibility_date钉住运行时行为相当于日期版本号不要抄别人的日期也不要写未来日期compatibility_flags开启额外特性如nodejs_compat按需开开了会增加包体积vars明文环境变量只能放非敏感配置密钥一律走 secret[[kv_namespaces]]等各类资源绑定名字要和代码里env.后面的保持一致compatibility_date这个字段最容易被低估。它本质上是一个「运行时行为快照」写一个较早的日期你会保留旧行为写一个较新的日期你会拿到最新的默认行为。这里有个坑——很多人为了「用上新特性」把日期写成未来的某一天。这样做等于提前接受了还没正式默认开启的行为变更一些依赖库可能莫名其妙挂掉而且排查起来毫无头绪。我的原则是只在需要某个明确的变更时才往前推这个日期并且推完之后一定跑一遍完整回归。name也值得多说一句。它决定了这个 Worker 的默认访问域名同时是部署时的唯一标识。改掉name的效果不是「重命名」而是「新建一个 Worker旧的还在」。有一次我们想把项目名改得规范一点改完之后发现访问地址变了旧域名上还挂着上一版代码白白多花时间清理。2.2 绑定Worker 伸出去拿资源的那只手Worker 本身是个轻量的执行单元它自己不带数据库、不带对象存储。要访问外部资源靠的就是「绑定」。绑定的工作机制很有意思你在配置文件里声明「我要用这个 KV 命名空间」部署的时候平台把访问凭据注入到运行时代码里直接用env.MY_KV就能拿到一个已经连好的对象。你不需要在代码里写地址、写 Token、做鉴权握手——这些全被平台接管了。好处是密钥不会出现在代码里坏处是本地调试时你得用同样的方式声明否则env.MY_KV就是undefined。常见的绑定类型我整理了一下按使用频率排序KV键值存储适合配置、会话数据、缓存。读取很快写入有延迟不适合强一致场景。R2对象存储放文件、图片、备份。接口风格接近 S3但没有出网流量费这个说法。D1基于 SQLite 的关系型数据库适合中小规模的结构化数据。Durable Objects有状态对象适合协作编辑、房间、计数器这类需要单点状态的场景。Queues消息队列用来削峰和异步处理。Service BindingsWorker 之间互相调用走内部通道不用绕公网。新手最容易犯的错是绑定名和代码变量名对不上。配置文件里写binding MY_KV代码里写env.KV本地一跑就是 undefined报错信息还特别含糊。我现在的做法是绑定名统一大写加下划线代码里严格照抄不给自己留犯错空间。2.3 本地模式和远程模式到底该选哪个wrangler dev有两个模式差别比想象中大。维度本地模式默认远程模式--remote运行位置本机模拟运行时真实边缘节点启动速度秒级需要打包上传慢一些数据来源本地隔离的模拟存储真实的 KV / D1 / R2资源消耗吃本机 CPU 和内存走线上配额适合场景日常开发、写业务逻辑验证绑定、排查线上差异本地模式的存储默认是临时的重启就没了。如果你在测一段依赖数据的逻辑每次重启都要重新灌数据非常折磨。加一个--persist-to .wrangler/state参数数据就会持久化到这个目录里重启后还在。这个目录记得加进.gitignore不然哪天不小心提交了一堆本地测试数据上去。我个人的工作流是写代码时用本地模式写完逻辑之后用--remote跑一次确认绑定和真实数据读写都没问题再去部署。这样能提前发现九成以上的「本地能跑线上不行」问题。3. 从空目录到一个能上线的 Worker完整实操3.1 环境准备与登录方式先把 Node 版本确认一下现在建议用 Node 20 的 LTS 版本太老的版本会在依赖安装阶段就报错。node -v npm -v然后是登录。日常开发用浏览器授权最省事npx wrangler login它会拉起浏览器授权完成后终端会提示成功。想确认当前身份跑一句npx wrangler whoami这条命令会同时打印出账号信息和当前使用的 API Token 权限。养成部署前先跑一次的习惯能避免很多「明明登录了却说没权限」的困惑。如果你的环境没法打开浏览器也可以走 API Token 的方式设置环境变量即可export CLOUDFLARE_API_TOKEN你的令牌 export CLOUDFLARE_ACCOUNT_ID你的账号ID令牌的权限要按需开给太多权限在团队里是不合适的做法。我一般只给脚本编辑和对应存储的读写权限够用就行。3.2 初始化项目与最小可用代码官方推荐的初始化方式是npm create cloudflarelatest my-worker交互过程中会问你要不要 TypeScript、要不要模板、要不要部署。跟着选就行。老版本的wrangler init已经被移除网上很多教程还在用这个命令照着敲会报错这一点要留意。如果你想完全手动控制也可以手写一个最小项目mkdir my-worker cd my-worker npm init -y npm i -D wrangler mkdir src然后建一个wrangler.tomlname my-worker main src/index.js compatibility_date 2024-09-23再写入口文件export default { async fetch(request, env, ctx) { const url new URL(request.url); if (url.pathname /health) { return new Response(ok, { status: 200 }); } return new Response(Hello from edge, { headers: { content-type: text/plain; charsetutf-8 }, }); }, };这十几行就是最小可运行单元。request是进来的请求env是所有绑定的集合ctx用来做等待后台完成的任务。三个参数各管一摊分工很清楚。3.3 本地调试的正确打开方式启动本地服务npx wrangler dev默认会监听一个本地端口直接打开浏览器或curl就能访问curl -i http://localhost:8787/health几个我常用的参数--port 8788换个端口避免和别的服务撞车。--persist-to .wrangler/state本地数据持久化重启不丢。--remote连真实资源跑用来验证绑定。--var KEY:value临时覆盖配置里的明文变量调参很方便。想看线上实时日志用npx wrangler tail它会挂着不动把每一次请求的日志、异常、耗时都打出来。排查线上问题时这条命令比什么都好使——我在生产环境遇到 500第一反应永远是开一个tail然后在另一个窗口复现请求看它到底在哪一行炸了。本地还有个隐藏福利wrangler dev启动时会在日志里打印一个调试器地址把它粘到浏览器的开发者工具里就能对 Worker 代码下断点跟调试前端代码几乎一样。这个功能很多人不知道用过之后基本就回不去了。3.4 部署、版本管理与回滚正式推之前先做一次「空跑」npx wrangler deploy --dry-run --outdirdist这个命令不会真的部署只做打包并把产物写到dist目录。好处是你能看到打包结果有多大、有没有意外把不该打进去的文件带上。我把它加进了提交前的检查脚本拦过好几次「不小心 import 了整个测试数据集」的低级错误。确认没问题就推npx wrangler deploy部署完查看历史版本npx wrangler versions list npx wrangler deployments list真出事了要退回去npx wrangler rollback不指定版本号时它会回滚到上一个版本也可以显式指定某个版本。这个能力是我坚持用命令行而不是控制台的主要原因之一——出问题的时候回滚动作越快越好一秒钟都不该浪费在找按钮上。3.5 把 KV、D1、R2 接上三个完整例子先说 KV。创建命名空间npx wrangler kv namespace create MY_KV命令会返回一个 id把它写进配置[[kv_namespaces]] binding MY_KV id 命令返回的id代码里直接读写export default { async fetch(request, env) { await env.MY_KV.put(greeting, hello); const value await env.MY_KV.get(greeting); return new Response(value ?? empty); }, };再说 D1。创建数据库npx wrangler d1 create blog-db配置[[d1_databases]] binding DB database_name blog-db database_id 命令返回的id准备一个迁移文件migrations/0001_init.sqlCREATE TABLE posts ( id INTEGER PRIMARY KEY AUTOINCREMENT, title TEXT NOT NULL, created_at INTEGER NOT NULL );执行迁移并查询npx wrangler d1 migrations apply blog-db --local npx wrangler d1 migrations apply blog-db --remoteconst { results } await env.DB .prepare(SELECT id, title FROM posts ORDER BY created_at DESC LIMIT ?) .bind(10) .all();注意--local和--remote是两个独立的世界。本地迁移完不等于线上有表我第一次用的时候就是因为只跑了本地部署后接口一直报「no such table」翻日志才发现。现在我的习惯是两条命令连着敲宁可多敲一次。最后是 R2npx wrangler r2 bucket create my-bucket[[r2_buckets]] binding BUCKET bucket_name my-bucket// 上传 await env.BUCKET.put(uploads/a.txt, request.body); // 读取 const object await env.BUCKET.get(uploads/a.txt); if (!object) return new Response(Not found, { status: 404 }); return new Response(object.body);三个存储的代码风格高度统一都是env.绑定名.方法()。这种一致性是它设计上很讨喜的地方学一个基本就会用另外两个。4. 常见问题与排查技巧实录4.1 报错速查表下面这些是我在实际项目里反复遇到过的按「现象 → 原因 → 处理」整理成表出问题的时候直接对照。现象 / 报错大概率原因处理方式提示未登录或鉴权失败本地没登录或 Token 权限不足先跑wrangler whoami再补登录或加权限找不到入口模块main路径写错按项目根目录为基准重新核对用了 Node 内置模块打包失败没开兼容标志加上compatibility_flags [nodejs_compat]env.XXX是 undefined绑定没声明或名称大小写不一致对照配置文件逐字核对绑定名部署成功但线上直接 500运行时异常被吞掉了开wrangler tail在另一个窗口复现请求本地能读到数据远程读不到本地是隔离存储用--remote验证或检查线上迁移是否执行提示兼容日期在未来日期填写超前改回当前或近期的日期请求报 CPU 超限单次请求计算时间超限拆分逻辑把重活挪到队列里异步做每天固定时间开始失败免费额度用尽看用量统计评估是否升级方案配置改了但行为没变部署的不是同一份配置确认环境分支重新部署一次静态资源 404构建输出目录配错检查资源目录字段与本地构建产物路径这张表我没打算写得包罗万象但覆盖了日常八成以上的卡点。真正难的是那些不报错但行为不对的情况那基本都要靠日志和二分法定位。4.2 几个我踩过的坑都是文档里不写的第一个坑是环境变量和密钥的混淆。vars是明文会出现在配置文件和部署信息里只能放非敏感内容真正的密钥必须用命令单独写npx wrangler secret put API_KEY执行后终端会让你粘贴值输入的内容不会回显也不会进 Git。这里有个容易忽略的点密钥是绑定到具体环境的如果你分了staging和production两套环境需要分别写一遍。我见过有团队只在默认环境配了密钥切到预发环境就报错排查半天以为是代码问题。第二个坑是配置文件打架。新版本同时支持wrangler.toml、wrangler.json、wrangler.jsonc但如果一个项目里同时放了两个行为会变得很难预测。我建议团队统一一种并且只保留一个文件。迁移的时候先把旧的删掉再加新的别两个并存。第三个坑是控制台与配置文件的双向覆盖。手动在控制台改了路由或变量下一次deploy会把它冲掉反过来你在控制台临时加的绑定本地代码里如果没有声明本地跑起来就会 undefined。我的处理方式是控制台只做只读查看和紧急处置任何长期有效的改动都必须落回配置文件并在提交信息里写清楚原因。第四个坑是多环境切换时的参数遗漏。配置里用[env.staging]定义了一套环境之后部署时必须显式带上--env staging忘了带就会部署到默认环境。这个错误最危险的地方在于它不会报错——命令成功返回你以为推到预发了实际上直接上了生产。后来我们在 CI 脚本里把环境名写成变量只允许从流水线部署人工不直接敲 deploy 命令这类事故就再没出现过。第五个坑是本地产物目录没被忽略。.wrangler目录里会存本地状态和缓存体积不小。第一次不小心把它提交上去的时候仓库瞬间多了几十兆清理起来很麻烦。项目初始化后第一件事就是把.wrangler、dist、node_modules一起写进忽略文件。5. 把它放进工程化流程里5.1 CI 里的无交互部署Wrangler 在流水线里跑得很舒服因为它天生就是为无交互场景设计的。核心就两点用 API Token 代替浏览器登录用--env明确环境。下面是一个很朴素但够用的流水线片段name: deploy on: push: branches: [main] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 - run: npm ci - run: npx wrangler deploy --env production env: CLOUDFLARE_API_TOKEN: ${{ secrets.CF_API_TOKEN }} CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CF_ACCOUNT_ID }}几个实操细节值得说。Token 要放进仓库的加密变量里绝对不能硬编码在文件里Token 权限按最小必要给只开需要的那几项部署前建议加一步空跑检查能提前发现打包异常还有一点很关键——如果密钥是用secret put单独写进去的它不会跟着代码走每个环境的密钥要在初始化阶段配好一次之后代码部署不会影响它。另外建议在流水线里加一步部署后校验比如curl一下健康检查接口确认返回 200 才算成功。这比看部署命令的退出码可靠得多因为部署成功不等于服务可用。5.2 和前端框架、Pages 的关系很多人是在做前端项目时遇到这个工具的这里容易概念混淆我用一句话区分Workers 适合放接口、鉴权、边缘逻辑Pages 适合放静态站点和前端应用。部署一个已经构建好的前端产物命令很简单npm run build npx wrangler pages deploy ./dist本地预览 Pages 项目用npx wrangler pages dev ./dist它会在本地起一个服务同时模拟 Pages 的运行环境包括函数路由。如果你做的是前后端一体的方案还有一种做法是把静态资源直接挂到 Worker 上在配置里声明资源目录让同一个 Worker 既处理接口又返回页面。这条路的好处是部署单元只有一个坏处是构建产物要跟代码一起管团队要约定好目录结构。我的建议是纯静态站用 Pages接口和边缘逻辑用 Workers两者混用的时候再考虑合并。别为了「看起来简洁」把明明分离的两件事硬塞进一个部署单元。顺带说一句主流前端框架的构建工具生态里已经有官方维护的适配插件能把开发服务器和 Worker 运行时接在一起本地开发体验会好很多。如果你的项目正好是这套技术栈值得花半小时看一下相关文档。5.3 什么时候我不建议用它工具好不好用关键看场景合不合。下面这几种情况我会劝人别硬上。需要完整操作系统能力的时候。如果你的服务依赖本地文件系统读写、需要调用系统命令、或者依赖某个只能在完整运行时跑的原生模块这套运行时就撑不起来。它的设计前提就是轻量、快启动、无状态硬要把重后端的东西塞进去只会一路碰壁。需要长时间后台任务的时候。单次请求的计算时间是有限额的免费方案尤其紧。如果你有一段要跑几十秒的批处理逻辑正确的做法是拆成消息队列加异步消费而不是硬扛。我第一次写数据同步脚本时就是因为这个栽了跟头本地跑得好好的线上总在某个临界点失败后来才意识到是计算时间超了。团队完全没有相关经验且项目是传统单体应用的时候。迁移成本不只是改代码还包括监控、日志、调试方式的整体转变。我的经验是先在边缘侧找一个独立的小功能试水比如图片处理、简单的接口聚合跑顺了再扩大范围。反过来如果你的场景是接口聚合、鉴权前置、静态资源分发、轻量 API那它几乎是目前最省心的选择之一。部署一条命令回滚一条命令不用管服务器不用管证书这种体验用过就很难回去了。最后分享两个我现在的固定习惯。一是把空跑检查加入提交前脚本让打包体积和文件清单每次都被看见一次问题暴露得越早越便宜。二是用一条生成类型定义的命令把env上所有绑定的类型自动产出来写 TypeScript 的时候编辑器能直接提示env.MY_KV有哪些方法不用再去翻文档。这两件小事加起来不到十分钟的配置成本但省下来的时间是以月计的。
Wrangler 实战：Cloudflare Workers 部署、调试与回滚指南
Wrangler 这个词丢进搜索框会撞出好几拨完全不相干的结果一款方头方脑的硬派越野车、一个做牛仔服饰的老牌子还有一大片出现在开发者社区里的终端截图。如果你是在翻文档、看部署日志的时候碰到它的那大概率指的是第三样——Cloudflare 官方出品的 Workers 命令行工具。它本身不写业务逻辑也不管你的界面好不好看它只负责一件事把本地这份代码用可复现、可回滚、可进代码仓库的方式推到边缘节点上跑起来。我前后用它带过几个小项目从最早的wrangler publish时代一路用到现在的wrangler deploy中间踩过的坑不算少。这篇就当成一次完整的项目复盘来写它到底解决什么问题、配置文件里哪几个字段必须动、本地调试和线上调试差在哪、KV/D1/R2 这些存储怎么接、部署翻车了怎么回滚以及它在什么场景下其实不适合用。刚接触 serverless 的同学可以照着顺序抄一遍已经用过几次但总在报错里打转的可以直接跳到第四节的排查表。1. Wrangler 到底是什么先把它解决的问题说清楚1.1 一句话定义以及三个最常见的误解Wrangler 是 Cloudflare 官方维护的命令行工具服务于 Workers 这套运行时的开发与部署全流程。我更喜欢把它理解成「脚手架 打包器 部署器」三合一create帮你在空目录里搭出骨架dev在本地起一个模拟运行时并把你的代码打进去deploy把打包产物连同配置一起上传。整个过程不需要你手动开控制台点按钮。围绕它的误解主要有三个。第一个是把它当成框架——不是的它完全不侵入代码结构你的入口文件就是普通的 JavaScript 或 TypeScriptexport default { fetch }这样导出就行换成别的构建工具照样能跑Wrangler 只是负责把它送上云。第二个是觉得必须全局安装——我早期也是npm i -g wrangler结果同时维护三个项目时版本互相打架命令参数都不一样。后来改成每个项目里npm i -D wrangler用npx wrangler调用问题立刻消失。第三个是以为wrangler dev起来的就是「线上环境」——默认情况下它跑的是本地模拟运行时数据是隔离的很多行为跟真实边缘节点并不完全一致这点后面会专门讲。把这三个误解捋顺后面看配置和报错就顺多了。1.2 为什么不用控制台点鼠标核心价值是可复现控制台上点几下也能上线一个 Worker。那为什么还要折腾命令行答案不在「快」而在「可复现」。Worker 上线需要一堆参数入口脚本、兼容性日期、环境变量、绑定关系、路由规则、自定义域名。这些如果只存在控制台里就会带来一连串麻烦改了什么没人能 diff、出问题回不到上一版、新人接手只能靠截图和口口相传。而 Wrangler 把这些全部收进一个wrangler.toml或wrangler.jsonc里这个文件跟着代码进 Git 仓库谁都能看到「现在线上到底是什么配置」。我遇到过最典型的一次事故某个同事在控制台手动加了一个 KV 绑定本地配置文件里没同步。两周后另一个人重新部署线上的绑定被覆盖掉接口直接 500。排查了快一小时才发现是「配置漂移」。从那以后我们定了规矩——所有跟 Worker 相关的改动必须走配置文件 Pull Request控制台只用来查看和应急处置。这就是 Wrangler 最实在的价值把「线上状态」变成一份可以被审阅的文本。1.3 它的边界在哪里别指望它包办一切用久了会形成一种错觉觉得 Wrangler 什么都能干。实际上它的边界挺清晰的。它不负责数据库的结构演进——D1 的建表和变更要靠wrangler d1 migrations配合 SQL 文件来做版本管理还得你自己盯。它不负责前端框架的构建——TypeScript 转译、CSS 处理、代码分割这些交给 Vite、esbuild 之类的工具Wrangler 只处理最后一步打包和上传。它也不能替你在线上做断点调试——wrangler tail能看实时日志但想看变量快照还是得靠本地复现加上日志打点。另外一点要有心理预期本地模拟和线上真机之间一定存在差异。本地用的是受限的执行环境某些 API 是模拟实现边界的网络行为、超时表现都不一样。我的习惯是本地跑通之后先用一个测试域名部署一版用wrangler tail观察真实流量下的表现确认没问题再切正式路由。这个「两段式上线」的习惯帮我拦下过好几次本地完全看不出来的问题。2. 核心概念拆解配置文件、绑定与运行环境2.1 wrangler.toml 里必须搞懂的字段配置文件是整套流程的中枢。字段看着多真正每次都要打交道的其实就是下面这几个。字段作用我的实操经验nameWorker 名称决定默认域名前缀改名字等于新建一个 Worker别随手改main入口文件路径写错会报模块找不到路径相对项目根目录compatibility_date钉住运行时行为相当于日期版本号不要抄别人的日期也不要写未来日期compatibility_flags开启额外特性如nodejs_compat按需开开了会增加包体积vars明文环境变量只能放非敏感配置密钥一律走 secret[[kv_namespaces]]等各类资源绑定名字要和代码里env.后面的保持一致compatibility_date这个字段最容易被低估。它本质上是一个「运行时行为快照」写一个较早的日期你会保留旧行为写一个较新的日期你会拿到最新的默认行为。这里有个坑——很多人为了「用上新特性」把日期写成未来的某一天。这样做等于提前接受了还没正式默认开启的行为变更一些依赖库可能莫名其妙挂掉而且排查起来毫无头绪。我的原则是只在需要某个明确的变更时才往前推这个日期并且推完之后一定跑一遍完整回归。name也值得多说一句。它决定了这个 Worker 的默认访问域名同时是部署时的唯一标识。改掉name的效果不是「重命名」而是「新建一个 Worker旧的还在」。有一次我们想把项目名改得规范一点改完之后发现访问地址变了旧域名上还挂着上一版代码白白多花时间清理。2.2 绑定Worker 伸出去拿资源的那只手Worker 本身是个轻量的执行单元它自己不带数据库、不带对象存储。要访问外部资源靠的就是「绑定」。绑定的工作机制很有意思你在配置文件里声明「我要用这个 KV 命名空间」部署的时候平台把访问凭据注入到运行时代码里直接用env.MY_KV就能拿到一个已经连好的对象。你不需要在代码里写地址、写 Token、做鉴权握手——这些全被平台接管了。好处是密钥不会出现在代码里坏处是本地调试时你得用同样的方式声明否则env.MY_KV就是undefined。常见的绑定类型我整理了一下按使用频率排序KV键值存储适合配置、会话数据、缓存。读取很快写入有延迟不适合强一致场景。R2对象存储放文件、图片、备份。接口风格接近 S3但没有出网流量费这个说法。D1基于 SQLite 的关系型数据库适合中小规模的结构化数据。Durable Objects有状态对象适合协作编辑、房间、计数器这类需要单点状态的场景。Queues消息队列用来削峰和异步处理。Service BindingsWorker 之间互相调用走内部通道不用绕公网。新手最容易犯的错是绑定名和代码变量名对不上。配置文件里写binding MY_KV代码里写env.KV本地一跑就是 undefined报错信息还特别含糊。我现在的做法是绑定名统一大写加下划线代码里严格照抄不给自己留犯错空间。2.3 本地模式和远程模式到底该选哪个wrangler dev有两个模式差别比想象中大。维度本地模式默认远程模式--remote运行位置本机模拟运行时真实边缘节点启动速度秒级需要打包上传慢一些数据来源本地隔离的模拟存储真实的 KV / D1 / R2资源消耗吃本机 CPU 和内存走线上配额适合场景日常开发、写业务逻辑验证绑定、排查线上差异本地模式的存储默认是临时的重启就没了。如果你在测一段依赖数据的逻辑每次重启都要重新灌数据非常折磨。加一个--persist-to .wrangler/state参数数据就会持久化到这个目录里重启后还在。这个目录记得加进.gitignore不然哪天不小心提交了一堆本地测试数据上去。我个人的工作流是写代码时用本地模式写完逻辑之后用--remote跑一次确认绑定和真实数据读写都没问题再去部署。这样能提前发现九成以上的「本地能跑线上不行」问题。3. 从空目录到一个能上线的 Worker完整实操3.1 环境准备与登录方式先把 Node 版本确认一下现在建议用 Node 20 的 LTS 版本太老的版本会在依赖安装阶段就报错。node -v npm -v然后是登录。日常开发用浏览器授权最省事npx wrangler login它会拉起浏览器授权完成后终端会提示成功。想确认当前身份跑一句npx wrangler whoami这条命令会同时打印出账号信息和当前使用的 API Token 权限。养成部署前先跑一次的习惯能避免很多「明明登录了却说没权限」的困惑。如果你的环境没法打开浏览器也可以走 API Token 的方式设置环境变量即可export CLOUDFLARE_API_TOKEN你的令牌 export CLOUDFLARE_ACCOUNT_ID你的账号ID令牌的权限要按需开给太多权限在团队里是不合适的做法。我一般只给脚本编辑和对应存储的读写权限够用就行。3.2 初始化项目与最小可用代码官方推荐的初始化方式是npm create cloudflarelatest my-worker交互过程中会问你要不要 TypeScript、要不要模板、要不要部署。跟着选就行。老版本的wrangler init已经被移除网上很多教程还在用这个命令照着敲会报错这一点要留意。如果你想完全手动控制也可以手写一个最小项目mkdir my-worker cd my-worker npm init -y npm i -D wrangler mkdir src然后建一个wrangler.tomlname my-worker main src/index.js compatibility_date 2024-09-23再写入口文件export default { async fetch(request, env, ctx) { const url new URL(request.url); if (url.pathname /health) { return new Response(ok, { status: 200 }); } return new Response(Hello from edge, { headers: { content-type: text/plain; charsetutf-8 }, }); }, };这十几行就是最小可运行单元。request是进来的请求env是所有绑定的集合ctx用来做等待后台完成的任务。三个参数各管一摊分工很清楚。3.3 本地调试的正确打开方式启动本地服务npx wrangler dev默认会监听一个本地端口直接打开浏览器或curl就能访问curl -i http://localhost:8787/health几个我常用的参数--port 8788换个端口避免和别的服务撞车。--persist-to .wrangler/state本地数据持久化重启不丢。--remote连真实资源跑用来验证绑定。--var KEY:value临时覆盖配置里的明文变量调参很方便。想看线上实时日志用npx wrangler tail它会挂着不动把每一次请求的日志、异常、耗时都打出来。排查线上问题时这条命令比什么都好使——我在生产环境遇到 500第一反应永远是开一个tail然后在另一个窗口复现请求看它到底在哪一行炸了。本地还有个隐藏福利wrangler dev启动时会在日志里打印一个调试器地址把它粘到浏览器的开发者工具里就能对 Worker 代码下断点跟调试前端代码几乎一样。这个功能很多人不知道用过之后基本就回不去了。3.4 部署、版本管理与回滚正式推之前先做一次「空跑」npx wrangler deploy --dry-run --outdirdist这个命令不会真的部署只做打包并把产物写到dist目录。好处是你能看到打包结果有多大、有没有意外把不该打进去的文件带上。我把它加进了提交前的检查脚本拦过好几次「不小心 import 了整个测试数据集」的低级错误。确认没问题就推npx wrangler deploy部署完查看历史版本npx wrangler versions list npx wrangler deployments list真出事了要退回去npx wrangler rollback不指定版本号时它会回滚到上一个版本也可以显式指定某个版本。这个能力是我坚持用命令行而不是控制台的主要原因之一——出问题的时候回滚动作越快越好一秒钟都不该浪费在找按钮上。3.5 把 KV、D1、R2 接上三个完整例子先说 KV。创建命名空间npx wrangler kv namespace create MY_KV命令会返回一个 id把它写进配置[[kv_namespaces]] binding MY_KV id 命令返回的id代码里直接读写export default { async fetch(request, env) { await env.MY_KV.put(greeting, hello); const value await env.MY_KV.get(greeting); return new Response(value ?? empty); }, };再说 D1。创建数据库npx wrangler d1 create blog-db配置[[d1_databases]] binding DB database_name blog-db database_id 命令返回的id准备一个迁移文件migrations/0001_init.sqlCREATE TABLE posts ( id INTEGER PRIMARY KEY AUTOINCREMENT, title TEXT NOT NULL, created_at INTEGER NOT NULL );执行迁移并查询npx wrangler d1 migrations apply blog-db --local npx wrangler d1 migrations apply blog-db --remoteconst { results } await env.DB .prepare(SELECT id, title FROM posts ORDER BY created_at DESC LIMIT ?) .bind(10) .all();注意--local和--remote是两个独立的世界。本地迁移完不等于线上有表我第一次用的时候就是因为只跑了本地部署后接口一直报「no such table」翻日志才发现。现在我的习惯是两条命令连着敲宁可多敲一次。最后是 R2npx wrangler r2 bucket create my-bucket[[r2_buckets]] binding BUCKET bucket_name my-bucket// 上传 await env.BUCKET.put(uploads/a.txt, request.body); // 读取 const object await env.BUCKET.get(uploads/a.txt); if (!object) return new Response(Not found, { status: 404 }); return new Response(object.body);三个存储的代码风格高度统一都是env.绑定名.方法()。这种一致性是它设计上很讨喜的地方学一个基本就会用另外两个。4. 常见问题与排查技巧实录4.1 报错速查表下面这些是我在实际项目里反复遇到过的按「现象 → 原因 → 处理」整理成表出问题的时候直接对照。现象 / 报错大概率原因处理方式提示未登录或鉴权失败本地没登录或 Token 权限不足先跑wrangler whoami再补登录或加权限找不到入口模块main路径写错按项目根目录为基准重新核对用了 Node 内置模块打包失败没开兼容标志加上compatibility_flags [nodejs_compat]env.XXX是 undefined绑定没声明或名称大小写不一致对照配置文件逐字核对绑定名部署成功但线上直接 500运行时异常被吞掉了开wrangler tail在另一个窗口复现请求本地能读到数据远程读不到本地是隔离存储用--remote验证或检查线上迁移是否执行提示兼容日期在未来日期填写超前改回当前或近期的日期请求报 CPU 超限单次请求计算时间超限拆分逻辑把重活挪到队列里异步做每天固定时间开始失败免费额度用尽看用量统计评估是否升级方案配置改了但行为没变部署的不是同一份配置确认环境分支重新部署一次静态资源 404构建输出目录配错检查资源目录字段与本地构建产物路径这张表我没打算写得包罗万象但覆盖了日常八成以上的卡点。真正难的是那些不报错但行为不对的情况那基本都要靠日志和二分法定位。4.2 几个我踩过的坑都是文档里不写的第一个坑是环境变量和密钥的混淆。vars是明文会出现在配置文件和部署信息里只能放非敏感内容真正的密钥必须用命令单独写npx wrangler secret put API_KEY执行后终端会让你粘贴值输入的内容不会回显也不会进 Git。这里有个容易忽略的点密钥是绑定到具体环境的如果你分了staging和production两套环境需要分别写一遍。我见过有团队只在默认环境配了密钥切到预发环境就报错排查半天以为是代码问题。第二个坑是配置文件打架。新版本同时支持wrangler.toml、wrangler.json、wrangler.jsonc但如果一个项目里同时放了两个行为会变得很难预测。我建议团队统一一种并且只保留一个文件。迁移的时候先把旧的删掉再加新的别两个并存。第三个坑是控制台与配置文件的双向覆盖。手动在控制台改了路由或变量下一次deploy会把它冲掉反过来你在控制台临时加的绑定本地代码里如果没有声明本地跑起来就会 undefined。我的处理方式是控制台只做只读查看和紧急处置任何长期有效的改动都必须落回配置文件并在提交信息里写清楚原因。第四个坑是多环境切换时的参数遗漏。配置里用[env.staging]定义了一套环境之后部署时必须显式带上--env staging忘了带就会部署到默认环境。这个错误最危险的地方在于它不会报错——命令成功返回你以为推到预发了实际上直接上了生产。后来我们在 CI 脚本里把环境名写成变量只允许从流水线部署人工不直接敲 deploy 命令这类事故就再没出现过。第五个坑是本地产物目录没被忽略。.wrangler目录里会存本地状态和缓存体积不小。第一次不小心把它提交上去的时候仓库瞬间多了几十兆清理起来很麻烦。项目初始化后第一件事就是把.wrangler、dist、node_modules一起写进忽略文件。5. 把它放进工程化流程里5.1 CI 里的无交互部署Wrangler 在流水线里跑得很舒服因为它天生就是为无交互场景设计的。核心就两点用 API Token 代替浏览器登录用--env明确环境。下面是一个很朴素但够用的流水线片段name: deploy on: push: branches: [main] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 - run: npm ci - run: npx wrangler deploy --env production env: CLOUDFLARE_API_TOKEN: ${{ secrets.CF_API_TOKEN }} CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CF_ACCOUNT_ID }}几个实操细节值得说。Token 要放进仓库的加密变量里绝对不能硬编码在文件里Token 权限按最小必要给只开需要的那几项部署前建议加一步空跑检查能提前发现打包异常还有一点很关键——如果密钥是用secret put单独写进去的它不会跟着代码走每个环境的密钥要在初始化阶段配好一次之后代码部署不会影响它。另外建议在流水线里加一步部署后校验比如curl一下健康检查接口确认返回 200 才算成功。这比看部署命令的退出码可靠得多因为部署成功不等于服务可用。5.2 和前端框架、Pages 的关系很多人是在做前端项目时遇到这个工具的这里容易概念混淆我用一句话区分Workers 适合放接口、鉴权、边缘逻辑Pages 适合放静态站点和前端应用。部署一个已经构建好的前端产物命令很简单npm run build npx wrangler pages deploy ./dist本地预览 Pages 项目用npx wrangler pages dev ./dist它会在本地起一个服务同时模拟 Pages 的运行环境包括函数路由。如果你做的是前后端一体的方案还有一种做法是把静态资源直接挂到 Worker 上在配置里声明资源目录让同一个 Worker 既处理接口又返回页面。这条路的好处是部署单元只有一个坏处是构建产物要跟代码一起管团队要约定好目录结构。我的建议是纯静态站用 Pages接口和边缘逻辑用 Workers两者混用的时候再考虑合并。别为了「看起来简洁」把明明分离的两件事硬塞进一个部署单元。顺带说一句主流前端框架的构建工具生态里已经有官方维护的适配插件能把开发服务器和 Worker 运行时接在一起本地开发体验会好很多。如果你的项目正好是这套技术栈值得花半小时看一下相关文档。5.3 什么时候我不建议用它工具好不好用关键看场景合不合。下面这几种情况我会劝人别硬上。需要完整操作系统能力的时候。如果你的服务依赖本地文件系统读写、需要调用系统命令、或者依赖某个只能在完整运行时跑的原生模块这套运行时就撑不起来。它的设计前提就是轻量、快启动、无状态硬要把重后端的东西塞进去只会一路碰壁。需要长时间后台任务的时候。单次请求的计算时间是有限额的免费方案尤其紧。如果你有一段要跑几十秒的批处理逻辑正确的做法是拆成消息队列加异步消费而不是硬扛。我第一次写数据同步脚本时就是因为这个栽了跟头本地跑得好好的线上总在某个临界点失败后来才意识到是计算时间超了。团队完全没有相关经验且项目是传统单体应用的时候。迁移成本不只是改代码还包括监控、日志、调试方式的整体转变。我的经验是先在边缘侧找一个独立的小功能试水比如图片处理、简单的接口聚合跑顺了再扩大范围。反过来如果你的场景是接口聚合、鉴权前置、静态资源分发、轻量 API那它几乎是目前最省心的选择之一。部署一条命令回滚一条命令不用管服务器不用管证书这种体验用过就很难回去了。最后分享两个我现在的固定习惯。一是把空跑检查加入提交前脚本让打包体积和文件清单每次都被看见一次问题暴露得越早越便宜。二是用一条生成类型定义的命令把env上所有绑定的类型自动产出来写 TypeScript 的时候编辑器能直接提示env.MY_KV有哪些方法不用再去翻文档。这两件小事加起来不到十分钟的配置成本但省下来的时间是以月计的。
