有段时间我每天要开好几个新虚拟机跑 Cloudflare Workers 的 Demo每次都要装 Node.js、Wrangler、Git还要配 SSH Key烦透了。后来我干脆把这一套东西固化成一个操作系统镜像命名为 cloudflare-os。它不是什么官方产品是我自己维护的一套基于 Alpine Linux 的定制环境专门为 Cloudflare 边缘开发设计。这篇文章就是想完整分享一下我从需求、构建到实测的整个过程包括踩过的坑和最终的使用感受。如果你经常处理 Workers、Pages 项目或者想要一个轻量的 CI 基础镜像我的这套配置和思路可以直接抄作业。1. 为什么需要 cloudflare-os普通开发环境的三个痛点先说清楚这玩意儿到底解决什么问题。Cloudflare 的官方文档写得再全也不会替你把本地环境收拾好。我过去三年在做云平台工具链日常和 Workers、Pages、Wrangler CLI 打交道发现每次环境搭建都在重复劳动而且坑点极其相似。1.1 每次从零搭建的重复劳动你算一下账新开一台机器先装 Node.js版本还得对得上项目要求然后装 Wrangler又得处理 npm 全局包权限问题接着配置 SSH KeyGit 身份顺便把常用 CLI 工具装齐。这一套动作手快也要半小时起步手慢点加上网络波动一下午就没了。我高峰期每周要建三个临时环境光这些准备工作就占掉不少时间。后来我想为什么不把这一整套环境直接打包成一个系统镜像启动即用所有工具预制好版本锁死不折腾。这就是 cloudflare-os 的最初动机——把环境搭建从每次重复变成一次投入。1.2 环境不一致导致的在我电脑上明明是好的在 Cloudflare Workers 项目里环境不一致是特别隐蔽的坑。本地 Node 版本是 18线上运行环境却是 20某些依赖的兼容性问题立刻就冒出来了。Wrangler 版本如果五花八门部署行为也会不一样哪怕同一个配置不同版本对路由规则的解析方式都可能不同。我见过同事因为本地 Wrangler 版本太老部署 KV 绑定的时候配置一直被自动忽略改了半天都是旧的。用 cloudflare-os 就是为了把开发环境混乱这个变量砍掉——镜像里预装的工具版本是经过实测的至少在知道自己在用什么版本这一件事上大家站在同一条起跑线。1.3 cloudflare-os 想解决什么说白了cloudflare-os 走的是最小可用 高度专用路线。它不是通用操作系统也不是什么发行版重打包而是给我自己以及类似处境的人一个可以复用的开发底座。它的核心目标有三个开箱即用拿到之后直接能跑 Wrangler 命令不需要任何额外安装步骤。版本可控Node.js、Wrangler、Git 和系统依赖全部锁定版本消除更新带来的惊喜。足够轻量镜像体积控制在 300MB 以内启动秒级内存占用低适合频繁创建销毁的使用场景。如果你只是偶尔碰一下 Cloudflare那这个镜像对你的意义不大。但如果你天天和 Workers 打交道或者想搭一套自动化的构建流水线cloudflare-os 就是一个不错的起点。2. 基础系统与组件选型我的几个关键决定做这个项目之前我认真比较了几种可行方案。原本想基于 Ubuntu 做因为生态最省心但最后我选了 Alpine Linux。这个选择不是拍脑袋而是有几个很具体的理由。2.1 用 Alpine 而不是 Ubuntu理由是体积和启动速度Alpine 的基础镜像只有 7MB 左右装上必要的运行时和工具链整体也能控制在 200MB 上下。Ubuntu 基础镜像动辄 150MB装完工具轻松到 800MB。在容器环境下镜像大不仅浪费磁盘每次拉取和启动都会多几秒如果你经常构建、销毁测试环境这点差异会累积成明显的卡顿。Alpine 的包管理器是 apk命令简洁装包速度也快。不过它有个特点必须提默认用的是 musl libc 而不是 glibc。这一点对 Cloudflare 原生 SDK 影响不大但对某些依赖原生模块的 npm 包会有兼容性问题。这个问题我后面在避坑记录里详细说当时真的花了我半天时间排查。2.2 预装工具链的取舍Wrangler、Node.js、Git 之外还需要什么既然是给 Cloudflare 开发用的系统最核心的三件套肯定是 Node.js、Wrangler 和 Git。但实际使用中你会发现光有这三样还不够。我在镜像里额外预装了这些curl 和 wget排查接口和下载文件的基本工具。jq处理 JSON 响应的利器尤其是调试 Workers 的返回结果时经常要用它提取字段。openssh用于连服务器或者传代码虽然大部分场景用 HTTPS但 SSH 总得有备无患。bashAlpine 默认是 ash功能够用但脚本语法和行为有差异用 bash 更顺手也让后续扩展脚本更安全。tzdata用来设置时区。如果你跑定时任务Cron Triggers默认 UTC 会对日志记录造成干扰。我一开始还想着要不要预装 Docker 或者 Podman后来想想违背了轻量专用的初衷就放弃了。你在 cloudflare-os 里需要构建容器镜像时最好在外部完成不要让这个开发环境参与容器构建。2.3 版本锁定的逻辑为什么不能随便用 latest在 cloudflare-os 里所有工具的版本都被我固定在一个明确的范围里。比如 Node.js我用的是 Node 20.x 系列而不是最新的 Node 22。原因是 Cloudflare Workers 运行时目前对 Node 20 的兼容性验证做得最好而且 Wrangler 的官方文档也是按 Node 20 来推荐的。如果你跟着最新版本跑哪天 Node 底层行为变化你的代码可能莫名其妙挂掉。Wrangler 我锁在 3.X 的某个特定小版本。Wrangler 更新频率很高但某些版本之间有 breaking change我实测过几次部署行为会有细微差异。在镜像里锁版本的好处就是无论你什么时候拉取 cloudflare-os你的核心工具一致性都能得到保证。因为镜像的构建过程是完全可复现的所以我也建议你在自己的项目里至少把 Wrangler 和 Node 的版本记录到一个.nvmrc或者.cloudflare-os-version文件里这样每台机器跑起来都是一个状态。3. 构建 cloudflare-os 的完整流程与避坑记录构建镜像的过程本身不复杂但有几个细节特别容易踩坑。我尽量把整个链路的关键节点都讲清楚尤其是我实际遇到的那些问题希望你能少走一点弯路。3.1 构建环境的选择Docker 里的多阶段构建我选择用 Docker 来构建 cloudflare-os。先写一个镜像构建文件然后从 alpine 基础镜像开始逐步安装依赖、复制脚本、设置环境变量。为了让最终镜像更干净我用了多阶段构建第一阶段负责下载安装各种工具包第二阶段只复制安装好的文件。这样既保证了构建过程的可复现性又能控制最终镜像的体积。具体的构建文件片段我放在这里你可以参考FROM alpine:3.19 AS builder RUN apk add --no-cache bash curl jq openssh git tzdata nodejs npm RUN npm install -g wrangler3.78.1 RUN mkdir -p /opt/cloudflare-os \ echo 3.78.1 /opt/cloudflare-os/wrangler.version \ echo 20.11.0 /opt/cloudflare-os/node.version FROM alpine:3.19 COPY --frombuilder /usr/bin/bash /usr/bin/bash COPY --frombuilder /usr/bin/curl /usr/bin/curl COPY --frombuilder /usr/bin/jq /usr/bin/jq ...构建的时候要注意npm install -g在 Alpine 上会把 Wrangler 装到/usr/local/bin或者/usr/bin下你最好在第二阶段显式地声明并且测试一下路径。不声明的话不同 Docker 版本的 PATH 设置可能导致命令找不到特别烦人。3.2 核心脚本拆解从基础镜像到最终打包构建过程里我写了一个脚本它的作用是基础系统装完包之后马上把 Wrangler 的自动补全和帮助文档这些杂物清掉然后生成一个环境检查的小脚本放到/usr/local/bin/cloudflare-info。这个小脚本会打出当前 Node、Wrangler、Git 的版本以及你最常用的几个环境变量是否存在。用的时候也很简单进入系统之后先跑一下cloudflare-info确认环境正常。如果哪天版本不对一目了然不用再到处查。构建脚本最主要的步骤大概是这样#!/bin/bash set -euo pipefail # 安装基础依赖 apk add --no-cache \ bash \ curl \ jq \ openssh \ git \ tzdata \ nodejs \ npm # 安装 Wrangler npm install -g wrangler3.78.1 # 设置时区 cp /usr/share/zoneinfo/Asia/Shanghai /etc/localtime echo Asia/Shanghai /etc/timezone # 生成环境检查脚本 cat /usr/local/bin/cloudflare-info EOF #!/bin/bash echo cloudflare-os 环境信息 echo Node.js $(node -v) echo Wrangler $(wrangler --version 2/dev/null || echo not found) echo Git $(git --version) env | grep -E CLOUDFLARE_(API_TOKEN|ACCOUNT_ID) || echo 未检测到 Cloudflare 凭据 EOF chmod x /usr/local/bin/cloudflare-info这里有个细节set -euo pipefail我用得非常认真。因为默认情况下如果某一条命令中间出错了后面的步骤会继续执行很容易掩盖问题。加上这个一旦关键步骤失败脚本立刻中断你能马上定位问题。3.3 登录授权问题无头环境下的 wrangler login 怎么处理我第一次把 cloudflare-os 跑起来之后想试试部署结果发现wrangler login在这个环境里根本没法用。因为它要求打开浏览器完成 OAuth 授权而我的镜像跑在虚拟环境里没有浏览器连图形界面都没有。这个问题其实在新环境里很常见。我最后用 API Token 解决了。你需要在 Cloudflare 控制台创建一个具有 Workers 权限的 API Token然后在环境变量里配置它export CLOUDFLARE_API_TOKEN你的token export CLOUDFLARE_ACCOUNT_ID你的账号ID设置完之后wrangler deploy就能正常工作了不需要走 OAuth 流程。我在镜像里故意没有把这两个变量写死而是保留成可注入状态这样镜像本身不携带任何敏感信息适合分发给别人。我还在 cloudflare-info 脚本里加了提示检测到没有凭据就明确告知避免你因为没配置 Token 而困惑。3.4 musl libc 与原生模块的兼容性坑这是我对 Alpine 印象最深的一个深坑。Wrangler 本身是纯 JS 包没太大问题但你后面想装一些带原生代码的 npm 依赖比如sharp、bcrypt或者某些数据库驱动它们默认从 npm 拉取的是基于 glibc 编译的二进制在 musl libc 环境下会直接报错。我当时想在这个镜像里装一个小的图片处理库结果一跑就提示 librarylibglib-2.0.so.0not found排查了一下午才发现是 musl 的锅。如果你确定要用 Cloudflare 周边生态尽量别装那些重度依赖原生模块的包或者你可以初始化一个apk包装上对应的 musl 兼容库但这会增大镜像体积。我的建议是如果需要复杂的图片处理或数据库操作把它放到其他服务里Cloudflare 环境只做纯转发或者轻计算。这本来就是 edge 开发的常见架构取舍cloudflare-os 只是把这个取舍固化到环境里好处是省心坏处是你得遵守它的边界。4. 实测与日常工作流cloudflare-os 到底好用在哪空说无用。我实际上用 cloudflare-os 跑了两个星期的日常开发包括新建项目、改代码、部署、调试。这里有一些实测数据和真实使用感受我认为比理论分析更有价值。4.1 内存和磁盘占用实测数据我拿一个普通的 4 核 8G 虚拟机来测试。启动系统之后不带任何跑着的 Worker只开一个终端空闲状态下内存占用大约 120MB 左右。如果同时跑 Wrangler 的dev模式内存会提升到 250MB 上下还在合理范围内。磁盘占用方面整个系统镜像打包后大约 220MB加上 Wrangler 缓存和临时文件总共占用 280MB 左右。这比传统 Ubuntu 桌面动辄几个GB的占用要清爽太多。另外我从启动虚拟机到能执行第一条wrangler命令耗时大约 4 秒。这个速度非常关键因为它让临时起一个环境变成一种很顺手的事情而不是像以前一样等待大半分钟。4.2 部署 Workers 项目的完整流程演示我给你走一遍最典型的流程。假设你要新建一个 Worker然后部署上去。在 cloudflare-os 里你只需要npx wrangler init my-worker cd my-worker npx wrangler dev没有npx版本选择困难没有权限报错因为全局 Wrangler 已经装好了。然后改一改src/index.ts再执行npx wrangler deploy如果配置了 Cloudflare API Token这一步几乎是秒部署。说实话最大的感受就是干净利落。在普通环境里这一步之前可能还要手动npm install wrangler然后再花好几秒钟等待安装。在 cloudflare-os 里所有准备动作都提前做完了。4.3 真实使用中需要留意的细节当然这镜像也不是万能的有几个细节要注意Wrangler 的缓存目录默认在~/.cache如果你跑测试要清缓存记得目录位置。因为镜像字体很精简终端里有些图形字符显示不出来比如 emoji 会显示成乱码我会直接避免在代码注释里用复杂字符。Alpine 的包管理器和 Ubuntu 不同如果你需要额外装系统包要用apk add千万别顺手敲了apt update。还有一点时区我默认设置成了中国时区但你如果跑海外节点的脚本记得检查时间同步问题不过一般影响不大。这些细节算不上什么大坑但提前知道的话整个使用体验会顺畅很多。5. 基于 cloudflare-os 的扩展玩法做到这里cloudflare-os 已经从一个个人便利工具慢慢变成一个可以拿来干正事的基座。它最直接的价值是可以自己用但更大的潜力在于复用。下面分享几个我后来实际尝试过的扩展方向。5.1 把它做成 CI 构建镜像如果你的项目用 GitHub Actions 或者 GitLab CI完全可以把 cloudflare-os 作为 CI 的基础镜像。这样每次跑流水线的时候就不会因为环境里有旧版本工具或者各种奇奇怪怪的配置导致失败。直接在 CI 配置里写jobs: build: runs-on: ubuntu-latest container: image: your-docker-hub/cloudflare-os:latest steps: - uses: actions/checkoutv4 - run: npx wrangler deploy这样 CI 执行时拉一套干净的环境Wrangler 版本是锁定的API Token 通过环境变量注入非常稳定。我在几个小项目里测试过流水线时长确实缩短了因为省去了每次安装工具的时间。唯一要提醒的是如果你在 CI 里需要 SSH 拉私有依赖记得把对应公钥放进镜像。5.2 配合 DevContainer 使用如果你用 VS Code 的 DevContainer 功能cloudflare-os 可以直接当一个 devcontainer 的镜像模板。你只需要在项目里建一个.devcontainer/devcontainer.json设置image: cloudflare-os然后每次打开项目VS Code 就会在一个已经配置好的环境里启动。这样团队里所有人共享一套开发环境不会再出现个人环境怪癖导致项目跑不起来。我在团队里推广过这个方案被吐槽最多的问题有两个一是镜像里没有预装 Zsh很多人习惯 Zsh 的插件二是某些人在 Windows 上用 DevContainer 连接有问题。但这两个问题都不难解决一个是加个包的事另一个是 Docker Desktop 的配置问题。5.3 后续可以继续加的工具和方向cloudflare-os 目前只覆盖了最核心的 Wrangler 开发流。我计划接下来加两个东西。一个是加入 Cloudflare 官方推出的多个辅助包比如cloudflare/workers-types和wrangler的自动补全脚本省得每次新建项目都自己配 TypeScript 环境。另一个是加入dns调试工具集如dig因为你在排查 Workers 路由和域名解析问题时dig是刚需。还有一个小方向是结合 Cloudflare Pages这台镜像里也预留了pages命令的入口只是我还没完全打磨。如果你有精力完全可以把wrangler pages的默认配置、静态文件上传工具也集成进来做成一个真正Frontend Edge一体化的环境。我在实际做这个项目时最大的体会是一个系统镜像表面上只是一个打包文件但它背后体现的是对待重复劳动的态度。环境搭得清爽效率才会跟着上去。cloudflare-os 这套做法不一定适合所有人但至少代表了一种思路——把你踩过的坑、用惯的工具、固定的版本全塞进一个可复用的盒子里从此每次开始一个新项目第一步都是靠谱的。