mcpField
C
cloudflare-mbt-worker-bundle

cloudflare-mbt-worker-bundle

github.com/mizchi开发41644 次安装1 周前更新
代码仓库

关于 cloudflare-mbt-worker-bundle

这是一个构建流水线模板，使用 cf 和 Cloudflare Vite 插件，将 MoonBit JavaScript 输出与 TypeScript Cloudflare Worker 入口打包。面向将 MoonBit 代码部署到 Workers 的团队，包含必要的输出改写和 bundle 检查。

主要功能

  1. 01MoonBit 到 JavaScript 的构建准备
  2. 02Worker FFI 源码改写
  3. 03cf 与 Vite 构建流水线
  4. 04检查生成的 bundle
  5. 05按模式配置 Worker

适用场景

  1. 01在 Worker 构建前准备 MoonBit 输出
  2. 02向 Cloudflare Workers 部署预构建 bundle
  3. 03检查生成 bundle 中的异常输出

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/mizchi/skills --skill cloudflare-mbt-worker-bundle

安装后在 Claude Code 中输入/cloudflare-mbt-worker-bundle确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

README.md
assets/scripts/
check-worker-bundle.test.ts
check-worker-bundle.ts
prepare-worker.ts.template
assets/templates/
cloudflare.config.ts.template
vite.config.ts.template
worker.ts.template
references/
cf-traps.md
moonbit-ffi-rewrites.md

详细介绍

Cloudflare Workers + MoonBit 打包流水线

使用 cf、cloudflare.config.ts 和 Cloudflare Vite 插件，将 MoonBit 的 JS 输出与 TypeScript Worker 入口打包在一起。当前的 cf/Vite 配置可参见 mizchi/cf-example（~/ghq/github.com/mizchi/cf-example）；其中检查过的版本是 cf beta.5 和适用于 Node.js 24 的 Vite 插件 beta。

流水线

moon build --target js --release
  → prepare-worker (FFI rewrites into src/_generated/<PKG>-core.js)
  → cf build --mode <mode>
  → check emitted bundle
  → cf deploy --prebuilt --mode <same-mode> --dry-run
  → cf deploy --prebuilt --mode <same-mode>

每次要发布包含 MoonBit 更改的构建前，都必须运行准备步骤。本地开发时，先准备生成的 JS，再运行 pnpm exec cf dev，并在 MoonBit 源码更改时重新生成；Vite 不会自动调用 moon build。

MoonBit 会输出纯 ESM JS。TypeScript 入口通过副作用导入已准备好的文件，该文件会注册 globalThis.__appServerFetch。导入原始的 _build/ 文件会绕过这些重写，可能导致 Worker 一直挂起。

对于此模板面向的运行时版本，需要进行两项源码重写：

  • 将 moonbitlang$async$internal$event_loop$$reschedule() 替换为生成的递归 reschedule 符号，以便等待中的工作能够恢复执行。
  • 将模块作用域中的随机种子初始化替换为确定性常量；Workers 不允许在模块初始化时进行随机 I/O。

如果找不到预期源码，requiredReplace 必须报错。升级 MoonBit/运行时时，应检查生成的代码并谨慎更新重写规则，而不是静默跳过。详情参见：moonbit-ffi-rewrites.md。

资源

  • worker.ts.template：导入 ./_generated/<PKG>-core.js 和遥测包装器的 TypeScript 入口。复制到 src/worker.ts；按需替换 <PKG> 和处理程序注册名称。
  • prepare-worker.ts.template：复制到 scripts/prepare-worker.ts，替换 <PKG>，应用两项 FFI 重写，并将准备好的 JS 写入 src/_generated/。
  • cloudflare.config.ts.template：复制到 cloudflare.config.ts。不同模式会选择生产/暂存 Worker 名称、D1 ID 和 R2 名称。完成资源配置后替换 ID；使用 cf d1 migrations apply DATABASE_ID --dir db/migrations 应用 D1 迁移。
  • vite.config.ts.template：cf dev/cf build 使用的 Vite 集成。
  • check-worker-bundle.ts：检查输出的 JS 包中是否存在损坏的控制字节、存根输出和项目专用标记。检查 worker.config.json 的清单以确定主模块，并传入其在 .cloudflare/output/v0/workers/<worker>/bundle/ 下的路径。如果 Vite 将模块拆分，应检查整个包目录，以涵盖其他模块中的标记。

使用 pnpm 添加 cf、@cloudflare/vite-plugin@beta、Vite 和 TypeScript，提交锁文件，使用 pnpm exec cf workers types 生成类型，并将 .cloudflare/types 加入 TypeScript 配置。预构建部署时也要使用 build 模式。对于必需的密钥绑定，在验证和部署时传入一个被忽略的 --secrets-file。

迁移现有 Worker 时，先运行 cf migrate --dry-run，再运行 cf migrate，然后再使用项目命令。保留先前的 DO 生命周期历史和资源 ID；不要初始化会丢失现有绑定的替代配置。参见 cf 配置指南。

参考资料

评论

支持 Markdown