Miniflare 常见陷阱

# 常见问题与故障排除 ## Miniflare 限制 **不支持：** - Analytics Engine (使用模拟) - Cloudflare Images/Stream - 浏览器渲染 API - Tail Workers - Workers for Platforms (部分支持) **与生产环境的行为差异：** - 在本地运行 workerd，而非 Cloudflare 边缘节点 - 存储是本地的 (文件系统/内存)，而非分布式 - `Request.cf` 是缓存/模拟的，而非真实的边缘数据 - 性能与边缘环境不同 - 缓存实现可能略有差异 ## 常见错误 ### "Cannot find module" **原因：** 模块路径错误或未配置 `modulesRules` **解决方案：** js new Miniflare({ modules: true, modulesRules: [{ type: "ESModule", include: ["**/*.js"] }], }); ### "Data not persisting" **原因：** 持久化路径是文件而非目录 **解决方案：** js kvPersist: "./data/kv", // 目录，而非文件 ### "Cannot run TypeScript" **原因：** Miniflare 不转译 TypeScript **解决方案：** 先使用 esbuild/tsc 构建，然后运行编译后的 JS ### "`request.cf` is undefined" **原因：** 未配置 CF 数据 **解决方案：** js new Miniflare({ cf: true }); // 或 cf: "./cf.json" ### "EADDRINUSE" 端口冲突 **原因：** 多个实例使用同一端口 **解决方案：** 使用 `dispatchFetch()` (无 HTTP 服务器) 或 `port: 0` 进行自动分配 ### "Durable Object not found" **原因：** 类导出与配置名称不匹配 **解决方案：** js export class Counter {} // 必须匹配 new Miniflare({ durableObjects: { COUNTER: "Counter" } }); ## 调试 **启用详细日志：** js import { Log, LogLevel } from "miniflare"; new Miniflare({ log: new Log(LogLevel.DEBUG) }); **Chrome DevTools：** js const url = await mf.getInspectorURL(); console.log(`DevTools: ${url}`); // 在 Chrome 中打开 **检查绑定：** js const env = await mf.getBindings(); console.log(Object.keys(env)); **验证存储：** js const ns = await mf.getKVNamespace("TEST"); const { keys } = await ns.list(); ## 最佳实践 **✓ 推荐：** - 测试时使用 `dispatchFetch()` (无 HTTP 服务器) - CI 中使用内存存储 (省略持久化选项) - 每个测试使用新实例以实现隔离 - 使用接口进行类型安全的绑定 - 在清理阶段使用 `await mf.dispose()` **✗ 避免：** - 在测试中使用 HTTP 服务器 - 未经清理共享实例 - 使用旧的兼容性日期 (使用 2026+) ## 迁移指南 ### 从 Miniflare 2.x 到 3+ v3+ 中的重大变更： | v2 | v3+ | |----|-----| | `getBindings()` 同步 | `getBindings()` 异步 |