Freebuff 发布启动器核心release-core深度解析createLauncher 的下载、自更新与崩溃兜底机制【免费下载链接】freebuffThe free coding agent项目地址: https://gitcode.com/GitHub_Trending/cod/freebuff导读cli/release-core/是 Freebuff、Codebuff、Codecane 三个产品共用的 npm 启动器launcher唯一权威实现。无论用户执行freebuff、codebuff还是codecane最终都由这个目录下的launcher.js完成检查版本 → 下载二进制 → 安装 → 拉起 TUI → 后台自更新 → 崩溃诊断兜底的全流程。读完本文你将掌握createLauncher(productConfig)的完整配置模型、prepack/postpack打包技巧、断点续传与原子安装原理以及针对老 CPU 的 AVX2 baseline 降级机制并能在本地用npm pack --dry-run验证三个产品的包装配。一、release-core 的定位一个工厂函数三个发布包cli/release-core/README.md开门见山地指出该目录是 Codebuff、Codecane 与 Freebuff 使用的 npm 启动器的 canonical权威实现。每个产品的发布包只维护一个很小的index.js向工厂函数createLauncher()注入自己的产品配置其余数百行启动逻辑全部复用同一份代码。三个消费方分别位于cli/release/index.js产品名codebuff包名codebuff同时提供codebuff与cb两个 bin 入口见 cli/release/package.jsonfreebuff/cli/release/index.js产品名freebuff自定义遥测事件名cli.update_freebuff_failedcli/release-staging/index.js产品名codecane是带醒目启动横幅的预发布staging环境includeTreeSitterWasm关闭、遥测属性带isStaging: true下载临时目录也独立为.download-temp-staging避免与正式包互相污染。以 cli/release/index.js 为例发布包内index.js的核心逻辑只有两件事优先require包内自带的launcher.js源码检出时才回退到../release-core/launcher.js然后调用工厂函数const launcher createLauncher({ packageName: codebuff, displayName: Codebuff, wrapperVersion: require(./package.json).version, tempDownloadDirName: .download-temp, })freebuff版在 freebuff/cli/release/index.js 中额外传入telemetryEvent: cli.update_freebuff_failed其余参数沿用默认值。当require.main module时执行launcher.main().catch(...)即作为 CLI 直接运行的入口。createLauncher 的完整配置项createLauncher的参数解构定义在 launcher.js下表汇总了所有可配置项及其默认值配置项类型默认值作用packageNamestring无必填产品名决定二进制文件名、User-Agent、元数据文件名、临时目录名与*_BINARY_TARGET环境变量前缀displayNamestring无必填下载完成后控制台展示的显示名wrapperVersionstring | nullnullnpm 包自身版本用于强制随包升级同步替换二进制includeTreeSitterWasmbooleantrue解压后是否把tree-sitter.wasm作为二进制旁边的兄弟文件安装startupBannerstring[][]启动时逐行打印的横幅codecane用它显示 STAGING 警告telemetryEventstringcli.update_codebuff_failed更新失败时上报到 PostHog 的事件名telemetryPropertiesobject{}附加到遥测事件的属性tempDownloadDirNamestring.\${packageName}-download-temp下载/解压的临时目录名configDirstring | nullnull仅供测试覆盖配置目录默认取~/.config/manicode二、打包与发布prepack/postpack 如何保证 npm 包自包含发布到 npm 的包必须独立可运行不能依赖仓库内其他目录。因此三个发布包在package.json的scripts里统一挂接了打包生命周期钩子例如 cli/release/package.jsonscripts: { prepack: node ../release-core/prepare-package.js, postpack: node ../release-core/prepare-package.js --clean }prepare-package.js的实现非常简短见 prepare-package.js只允许codebuff、codecane、freebuff三个包名通过防止意外装配prepack阶段把release-core下的launcher.js、http.js用fs.copyFileSync复制进包目录postpack阶段带--clean参数再把这两个生成文件删除保持源码检出干净它们已被 gitignore。这正是 README 强调的两点用户安装/卸载时不会有任何生命周期脚本执行二进制下载发生在运行时而非postinstall以及修改启动器行为时应改release-core并重新装配验证。装配验证命令在 cli/release-core/README.md 中给出三个包逐一 dry-runnpm pack ./cli/release --dry-run npm pack ./cli/release-staging --dry-run npm pack ./freebuff/cli/release --dry-run--dry-run会在本地模拟打包但不产出 tarball可确认files字段index.js、launcher.js、http.js、README.md是否都收录、tar依赖是否就位。发布包的基础约束三个包的package.json遵循同样的发布约束bin把index.js暴露为全局命令codebuff/cb、freebuff、codecaneos限定darwin/linux/win32cpu限定x64/arm64不满足的平台直接拒绝安装engines.node 16因为启动器使用了child_process.spawn、stream/promises、zlib等现代 Node API唯一的运行时依赖是tar解压 tarball 用整个 HTTP 客户端是零依赖手写实现刻意不引入axios之类的第三方请求库。三、启动主流程main() 的四个阶段main()定义在 launcher.js依次执行async function main() { for (const line of startupBanner) { console.log(line) } if (startupBanner.length 0) console.log() await ensureBinaryReady() const child spawnInstalledBinary() const exitListener attachExitHandler(child) setTimeout(() { checkForUpdates(child, exitListener) }, 100) }四个阶段依次是打印启动横幅staging 环境可见ensureBinaryReady()同步确认本地二进制可用缺失或过旧时先下载安装spawnInstalledBinary()以继承的 stdin/stdout 拉起真正的 TUI 二进制并注入CODEBUFF_LAUNCHER_PID环境变量launcher.js让子进程知道我由 launcher 托管100ms 后触发后台更新检查不阻塞首屏启动子进程先跑起来更新在后台静默完成。ensureBinaryReady还处理了一个易被忽视的坑npm install会更新这个 JS 包装器但会保留已下载的二进制如果二进制早已失效就会永远卡在启动前。因此它会在健康启动路径上同步修复过期缓存而不必每次启动都查 registrylauncher.js。四、版本判定与平台目标选择从 npm registry 取最新版本getLatestVersion()直接请求https://registry.npmjs.org/${packageName}/latest并解析version字段launcher.js。失败时返回null调用方会给出无法确定最新版本请检查网络连接的错误提示。本地元数据与缓存校验安装状态记录在~/.config/manicode/${packageName}-metadata.json中Windows 之外同理内容形如{ version: 1.0.688, target: linux-x64 }。getCurrentVersion()在读取元数据时还会做三重校验元数据文件存在、binaryPath对应的二进制文件真实存在、metadata.target仍被当前机器允许任何一项不满足都视为未安装launcher.js。自实现的 semver 比较器为避免引入依赖launcher.js用正则 BigInt手写了严格的 semver 解析与比较parseVersion/compareVersions见 launcher.js支持主.次.补丁、预发布标识符、数字/字符串标识符比较对畸形版本按过时处理从而触发自愈式重新下载。平台目标Platform Target表PLATFORM_TARGETS定义了 7 种可下载产物launcher.js目标键文件名linux-x64{packageName}-linux-x64.tar.gzlinux-x64-baseline{packageName}-linux-x64-baseline.tar.gzlinux-arm64{packageName}-linux-arm64.tar.gzdarwin-x64{packageName}-darwin-x64.tar.gzdarwin-arm64{packageName}-darwin-arm64.tar.gzwin32-x64{packageName}-win32-x64.tar.gzwin32-x64-baseline{packageName}-win32-x64-baseline.tar.gzbaseline后缀代表面向不支持 AVX2 老 CPU的兼容构建目前只存在于linux-x64与win32-x64见BASELINE_FALLBACK_TARGETSlauncher.js。下载 URL 由三部分拼装而成launcher.jsconst downloadUrl ${ process.env.NEXT_PUBLIC_CODEBUFF_APP_URL || https://codebuff.com }/api/releases/download/${version}/${fileName}目标键的覆盖机制用户可通过环境变量强制指定目标键优先级从高到低为launcher.js${PACKAGENAME}_BINARY_TARGET如FREEBUFF_BINARY_TARGETCODEBUFF_BINARY_TARGETCLI_BINARY_TARGET。设置后所有下载/校验都锁定该目标且崩溃兜底逻辑会尊重这一显式选择见第八节。五、下载断点续传、进度与重试分层设计下载能力拆成两层http.js 中的createReleaseHttpClient()无框架 HTTP 客户端负责代理、重定向、超时与断点续传返回{ downloadFile, httpGet, withRetries }launcher.js 中的downloadAndExtract()负责重试编排、进度展示、gunzip tar 解压与产物校验。launcher.js创建客户端时传入三个关键参数launcher.jsconst CONFIG createConfig(packageName) const { downloadFile, httpGet, withRetries } createReleaseHttpClient({ env: process.env, userAgent: CONFIG.userAgent, // ${packageName}-cli requestTimeout: CONFIG.requestTimeout, // 20000ms })createConfig()里还有几个调优值launcher.js普通请求超时20000ms、下载请求超时120000ms、最大下载尝试次数3。断点续传与 Range 语义downloadFile的实现见 http.js核心行为下载前先stat目标.part文件大小若大于 0 则自动附带Range: bytes{size}-头服务器回206 Partial Content且Content-Range起点吻合时以a追加模式续写回200表示服务器忽略 Range则从零重写避免把完整响应追加到旧残片上回416且Content-Range的 total 恰好等于已下载字节数时视为已完整直接返回响应体长度与Content-Range不一致时抛EINCOMPLETE错误并标记为可重试。指数退避重试withRetries实现了baseDelayMs * 2^(attempt-1)的指数退避http.js默认基础延迟 1s。可重试判定isRetryableDownloadError排除EACCES/ENOSPC/EPERM/EROFS等重试也没用的本地文件系统错误launcher.js。下载失败的可读性设计失败时打印的信息非常讲究printDownloadFailurelauncher.js显示已保存的字节数与总字节数并提示下次运行会续传能区分下载源不可达请重试与解压/安装失败保留旧二进制两类场景解压失败会删除.part文件因为完整但无法解压的归档是损坏的续传没有意义launcher.js。进度条是手写的 30 格[█░]渲染且做了 100ms 节流避免刷屏launcher.js。六、原子安装与回滚installStagedBinary下载完成后并不直接覆盖旧文件而是走暂存 → 备份 → 替换 → 提交/回滚的原子安装流程installStagedBinarylauncher.js先把{version, target}元数据写入${metadataPath}.new.${pid}临时文件replaceFileWithRollback(tempBinaryPath, binaryPath)若目标已存在先rename成带时间戳的.old.${Date.now()}备份再rename新文件就位若includeTreeSitterWasm且 tarball 内带有tree-sitter.wasm同样以备份-替换方式装到二进制旁边。源码注释解释了原因把 wasm 打进二进制bun --compileasset 打包在 Windows 上多次出现被静默丢弃的问题所以改走兄弟文件方案launcher.js最后替换元数据文件并commitReplacements清理备份。任何一步失败rollbackReplacements会把已替换的文件逐一还原保证用户机器上要么是完整的新版本要么是完整的旧版本绝无半新半旧状态。finally中清理临时目录与.new.*文件。非 Windows 平台安装后还会chmod 0o755赋予执行权限chmod 失败同样触发整体清理launcher.js。七、后台自更新checkForUpdates 与进程接管启动 100ms 后launcher 在后台检查更新checkForUpdateslauncher.js若子进程已经退出例如启动即崩溃并切换到 baseline直接放弃本轮更新避免与重启流程争抢共享临时目录比较当前版本与 registry 最新版本只有未知或落后才更新以quiet: true模式后台下载暂存新二进制不刷进度条用stopRunningProcess优雅停止旧进程先SIGTERM5 秒后仍不退则SIGKILL再等 1 秒仍不退出才报错launcher.js复位终端后打印Update available: 当前版本 → 新版本安装新二进制重启子进程若更新中途失败但旧二进制还在则用旧版本重启进程继续工作——更新失败绝不打断用户会话。需要说明的是这种停止-替换-重启的更新策略对交互式 TUI 会话是有打断成本的所以它被设计为后台任务并尽量静默且wrapperVersion机制getRequiredWrapperVersionlauncher.js保证 npm 包装器升级后能强制拉取配套二进制避免新壳带旧核。八、AVX2 检测与 baseline 兜底老 CPU 的崩溃恢复这是 launcher 里工程上最精细的部分。现代构建Bun 编译产物要求 CPU 支持 AVX2 指令集2013 年之前的 x64 CPU 无法运行。三层检测策略detectMachineHasAvx2launcher.js按优先级组合了三种手段崩溃记录优先cpu-features.json缓存里若记录了实测缺 AVX2直接采信——真实失败记录胜过任何推断Linux 主动探测读/proc/cpuinfo匹配avx2标志位成本极低Windows 乐观假设其他平台一律假设有 AVX2。源码注释解释了为什么不用 PowerShell 探测旧方案用 PowerShell 编译 C# stub 调IsProcessorFeaturePresent虽然准确但形似恶意软件被 Windows Defender 标记为 Suspicious PowerShell command line于是改为乐观启动 崩溃后纠正。崩溃纠正链路当子进程以非法指令类信号退出时attachExitHandler会调用tryFallbackToBaselinelauncher.js识别两种失败拼写SIGILL/STATUS_ILLEGAL_INSTRUCTION0xc000001d是确定性证据Windows 上的0xc0000409STATUS_STACK_BUFFER_OVERRUN即 Bun 用__fastfail报告的 Zig panic在启动后 10 秒窗口内STARTUP_CRASH_WINDOW_MS被视为强烈疑似——这是从真实线上事故oven-sh/bun#28399中总结出的坑无 AVX2 的 CPU 往往不是死在非法指令上而是死在 Bun 启动时的 panic 上只有确定性证据才写入cpu-features.jsonrecordMachineLacksAvx2把乐观假设的代价封顶为一次崩溃疑似证据只降级下载不落盘下载 baseline 版本、安装并重新拉起进程若用户已显式设置*_BINARY_TARGET则尊重用户选择不覆盖。getDefaultTargetKey中还保证一旦缓存记录了缺 AVX2后续启动会直接选 baseline不再重蹈崩溃launcher.js。崩溃报告与终端恢复printCrashDiagnosticslauncher.js能区分非法指令、访问违例0xc0000005、总线错误SIGBUS、中止SIGABRT四类崩溃打印系统信息平台/Node 版本/AVX2 支持状态/目标键/二进制路径并提示如何强制 baseline。终端在崩溃后必须复位resetTerminal会退出备用屏幕并发送一系列安全复位序列关闭鼠标模式、粘贴模式、focus 报告等防止子进程被强杀后留下坏终端launcher.js。崩溃现场还做了取证Windows 上 stderr 被 tee 下来保留最近 8192 字节STDERR_TAIL_BYTES崩溃报告会附上子进程最后输出且经过sanitizeForReplay清洗转义序列——否则复位后的终端可能被二进制残留的转义重新带入备用屏幕让报告本身不可见launcher.js。九、HTTP 客户端细节代理、重定向与超时createReleaseHttpClient依赖注入设计http.js把http/https/fs/pipeline/tls全部做成可替换参数便于测试注入 mock。代理逻辑支持HTTP_PROXY/HTTPS_PROXY及小写变体且 HTTPS 走代理时实现标准CONNECT隧道connectThroughProxyhttp.js支持代理的 Basic AuthURL 内嵌user:password。NO_PROXY/no_proxy支持*、.domain前缀与精确域名三种匹配http.js。httpGet对 301/302/303/307/308 重定向最多跟进 10 跳并在跳转时保留请求选项http.js。所有请求都有超时控制普通请求默认 20s下载 120s代理连接同样受超时约束。十、本地验证与测试装配验证修改 launcher 行为后README 建议用三条命令验证所有包装配npm pack ./cli/release --dry-run npm pack ./cli/release-staging --dry-run npm pack ./freebuff/cli/release --dry-run面向测试的内部接口createLauncher返回对象中除了config、main、stopRunningProcess外还通过__testing命名空间暴露了detectMachineHasAvx2、tryFallbackToBaseline、printCrashDiagnostics、getDefaultTargetKey、ensureBinaryReady等内部函数launcher.js。源码注释明确说明原因AVX2 路径是乐观假设 崩溃纠正而 CI 机器永远不缺少 AVX2无法用真实崩溃驱动测试因此必须直接对纠正逻辑做单测。另外createReleaseHttpClient的依赖注入设计让断点续传、代理、重定向等场景都可以用内存流 mock 验证。结语cli/release-core用不到两个文件实现了生产级启动器该有的全部能力零第三方依赖的 HTTP 客户端、Range断点续传、指数退避重试、原子安装回滚、后台自更新、跨平台崩溃诊断与 AVX2 baseline 兜底。它既是 Freebuff 等产品 npm 分发链路的心脏也是一份值得反复研读的 Node 工程范本。理解createLauncher的配置模型与prepack/postpack装配约定你就掌握了如何为一个编译型 CLI 产品搭建健壮的自更新发布体系。【免费下载链接】freebuffThe free coding agent项目地址: https://gitcode.com/GitHub_Trending/cod/freebuff创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考