Cherry Studio Linux 打包全指南基于 pinned better-sqlite3 预编译产物的构建、校验与更新流程【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio本指南聚焦 Cherry Studio 在 Linux 平台上的打包机制Linux 安装包AppImage / deb / rpm依赖从固定版本 Release 下载的 x64 与 ARM64better-sqlite3预编译产物prebuild并通过 beforePack / afterPack 钩子完成下载、校验与替换。读完本文你将掌握 Cherry Studio Linux 打包的完整命令、三步校验管线下载校验、electron-builder 原生依赖重建、打包后替换校验的实现细节以及当 Electron 或 better-sqlite3 升级时如何正确更新 pinned prebuild。背景为什么 Linux 包需要 pinned prebuildCherry Studio 使用 SQLite 存储本地数据而 better-sqlite3版本 12.11.1是包含 C 原生代码的 Node 插件。Electron 运行时自带的 V8/ABI 与系统 Node 不同任何 ABI 不匹配的原生模块都会在启动时崩溃。此外在打包机上现场编译原生模块往往产生对较新 GLIBC/GLIBCXX 的依赖导致产物在较老发行版如 CentOS 7、Ubuntu 18.04 系列上无法加载。为此Cherry Studio 采用固定版本pinned的预编译产物方案所有 Linux 安装包统一使用来自独立仓库CherryHQ/cherry-studio-better-sqlite3的 GitHub Release 中的better-sqlite3prebuild。该方案的核心约束记录在 release.json绝不指向浮动的latestRelease每次构建都锚定一个带版本号的精确 tag每个架构的 addon.node文件和 manifest.manifest.json都附带硬编码的 SHA-256 值Release 元数据Electron 版本、Electron ABI、better-sqlite3 版本必须与当前仓库实际安装的依赖完全一致否则构建直接失败。以当前仓库为例pinned 信息为Electron41.8.0、Electron ABI145、better-sqlite312.11.1Release tag 为better-sqlite3-v12.11.1-electron-v41.8.0-r1。构建命令与前置条件基础构建命令Cherry Studio 的 Linux 构建命令定义在 package.json 的scripts字段中# 同时构建 x64 与 arm64 两个架构 pnpm build:linux # 只构建单一架构 pnpm build:linux:x64 pnpm build:linux:arm64底层展开逻辑以build:linux为例dotenv pnpm run build electron-builder --linux --x64 --arm64即先执行完整的应用构建typecheckelectron-vite build utility process 构建再调用 electron-builder 针对 Linux 目标产出安装包。当前 electron-builder.yml 中 Linux 目标包括 AppImage、deb、rpm 三种格式产物命名形如${productName}-${version}-${arch}.${ext}。首次构建需要网络prebuild 缓存目录为scripts/linux-native/prebuilt/已被 Git 忽略不会入库。首次构建时beforePack钩子会发现缓存为空自动从 pinned GitHub Release 下载对应架构的.node与.manifest.json文件只有下载并验证通过后才写入缓存供后续构建复用。因此首次构建必须能访问 GitHub Release且网络环境需要能连通github.com。不需要 Docker / QEMUCherry Studio 自身的 Linux 打包不依赖 Docker 或 QEMU在 x64 主机上可以直接产出 arm64 安装包因为真正的原生二进制不是现场编译而是从预编译 Release 获取。Docker/QEMU 仅在需要从独立仓库发布新 prebuild 时才派上用场——那是维护者发布预编译产物时的工具与应用打包流程无关。相关环境约束从源码可以补充确认的几点前提包管理器为 pnpmpackageManager: pnpm11.8.0Node 版本约束为24.11.1 24.16.0见 package.json若同时打包多个架构electron-builder 的--x64 --arm64会分别触发两次打包流水线每次对应一个架构中国区构建走独立的build:linux:cn/build:linux:x64:cn/build:linux:arm64:cn使用 electron-builder.cn.config.cjs 作为配置但 Linux prebuild 校验与替换逻辑一致。打包流水线三步校验与替换整个 Linux 打包过程由 electron-builder.yml 中声明的两个钩子驱动beforePack: scripts/before-pack.js afterPack: scripts/after-pack.js第一步beforePack 下载并校验 pinned 产物before-pack.js 在应用文件拷贝进包之前执行。对于 Linux 平台它调用 download.js 的ensureLinuxNativeArtifact完成以下工作架构白名单检查仅接受x64/arm64其他架构直接报Unsupported Linux architectureRelease 元数据一致性校验assertReleaseMetadata将 release.json 中的electronVersion、electronAbi、betterSqlite3Version与当前仓库node_modules中实际安装的版本逐一比对通过 compat.js 的readProjectBuildMetadata读取并用node-abi解析当前 Electron 版本对应的 ABI 号任一字段不匹配即抛出field ... is stale错误并在下载前终止构建缓存复用或原子下载若scripts/linux-native/prebuilt/arch/下已存在通过完整校验的产物直接复用cached: true否则使用curl -fSL --retry 3 --connect-timeout 15 --max-time 120下载 addon 与 manifest 到临时目录逐字节校验 SHA-256 后原子替换缓存目录临时目录 rename避免半成品文件下载后完整校验verifyReleaseArtifact同时校验 pinned 的 Release 资产哈希与产物自身的原生兼容性详见下文第二步的校验项。成功后会打印类似日志Downloaded GLIBC-compatible better-sqlite3 for linux-x64 (sha256)第二步electron-builder 常规原生依赖重建下载校验通过后electron-builder 继续执行其常规的原生依赖重建流程。这里有一个值得注意的设计非 Linux 平台macOS / Windows走的是electron/rebuild从源码强制重编译better-sqlite3buildFromSource: true见 before-pack.js 的prepareNativeModulesForElectron而Linux 平台跳过源码编译、直接使用预编译产物——这正是better-sqlite3编译产物兼容性问题只在 Linux 上突出的原因也是本套方案存在的意义。第三步afterPack 校验并替换打包产物打包完成后after-pack.js 对 Linux 平台调用 compat.js 的replacePackagedBetterSqlite3将缓存的 prebuild 覆盖到包内目标路径resources/app.asar.unpacked/node_modules/better-sqlite3/build/Release/better_sqlite3.node替换前、替换后都会执行verifyNativeArtifact的六项校验全部通过才允许继续校验项实现位置说明Manifest schema 版本compat.jsschemaVersion必须为 2、platform必须为linux关键字段一致性同上arch、electronVersion、electronAbi、betterSqlite3Version必须与当前项目构建元数据一致ELF 架构detectElfArch校验魔数\x7fELF、64 位、小端且e_machine为 62x64或 183arm64ABI 版本上限assertVersionRequirements从二进制文本中解析所有GLIBC_/GLIBCXX_/CXXABI_符号版本取每个 family 的最大值不得超过上限glibc 2.28、glibcxx 3.4.25、cxxabi 1.3.11文件哈希sha256比对产物实际哈希必须与 manifest 记录的sha256一致Manifest 与产物一致性JSON.stringify比对manifest 中的requirements必须与产物解析出的版本要求完全一致替换时还通过fs.copyFileSyncchmodSync保持可执行权限位并对包内落盘文件再做一次完整校验防止打包过程引入损坏字节。任何一项失败都会抛出异常并中断打包——缺失、过期或与 ABI/架构不兼容的产物都不允许进入最终安装包。日志示例Installed GLIBC-compatible better-sqlite3 for linux-x64 at path (ABI 145, {glibc:2.28,...})测试覆盖该流程有完善的单测佐证见 linux-native.test.tsparseVersionRequirements对同一 ABI family 取最高版本号兼容产物通过校验x64 / arm64 各测一次而要求GLIBC_2.29的产物被拒绝错误架构、过期元数据、被篡改的字节均被拒绝分别报manifest field arch、manifest field electronVersion、checksum mismatchensureLinuxNativeArtifact首次下载、二次复用缓存且不再发起网络请求Release 元数据过期时在下载前即失败pinned Release 配置与当前仓库构建输入完全匹配且 tag 不含latest。更新 Prebuild 的完整步骤当Electron 版本升级或better-sqlite3 版本升级时旧 prebuild 将无法通过第一步的元数据一致性校验assertReleaseMetadata构建会以field ... is stale直接失败。此时需要按文档与源码约定的流程更新步骤 1从 prebuild 仓库发布已验证的 Release在独立的CherryHQ/cherry-studio-better-sqlite3仓库中针对新的 Electron / better-sqlite3 组合分别构建并发布 x64、arm64 的addon 文件better_sqlite3-better-sqlite3版本-electron-electron版本-linux-arch.nodemanifest 文件better_sqlite3-better-sqlite3版本-electron-electron版本-linux-arch.manifest.jsonmanifest 内需记录schemaVersion: 2、platform: linux、arch、electronVersion、electronAbi、betterSqlite3Version、sha256以及解析出的requirements见 compat.js 的校验契约。发布新 prebuild 的过程才需要 Docker / QEMU 等交叉编译与验证工具。步骤 2更新 release.json 的固定信息编辑 release.json同步更新{ schemaVersion: 1, repository: CherryHQ/cherry-studio-better-sqlite3, tag: better-sqlite3-vnew-version-electron-vnew-version-r1, metadata: { electronVersion: 新的 Electron 版本, electronAbi: 新的 ABI 号, betterSqlite3Version: 新的 better-sqlite3 版本 }, artifacts: { x64: { addon: { name: better_sqlite3-新版本-electron-新版本-linux-x64.node, sha256: 64 位十六进制哈希 }, manifest: { name: ..., sha256: ... } }, arm64: { /* 同上 */ } } }更新时需同时满足 download.js 中的格式约束repository必须匹配owner/repo形式、schemaVersion必须为 1、tag/metadata/artifacts三要素齐全、资产名只允许[A-Za-z0-9_.-]、sha256必须为 64 位小写十六进制。仓库中的测试linux-native.test.ts 的pinned Linux native release用例会校验release.json与仓库当前构建输入一致因此升级依赖后必须同步更新该文件否则 CI 与本地构建都会失败。规则红线禁止指向 floating latest文档明确强调Never point application builds at a floatinglatestRelease。这有两层含义release.json 的tag必须是精确的版本 tag测试中也有expect(config.tag).not.toContain(latest)的断言语义上应用构建的可复现性优先于总是拿到最新版——如果指向latest同一份代码在不同时间构建可能得到行为不同的二进制且无法追溯、无法回滚。常见问题速查现象原因处理首次构建卡在下载阶段scripts/linux-native/prebuilt/缓存为空需要访问 GitHub Release确认网络可达github.com重跑构建成功后缓存可复用field electronVersion is stale或 ABI / better-sqlite3 字段升级了 Electron 或 better-sqlite3但 release.json 未同步按上文更新 Prebuild流程发布新 Release 并更新release.jsonGLIBC_2.29 ... exceeding the 2.28 limit预编译产物在过新的系统上编译引入了过高 ABI 依赖更换在受控环境Docker/QEMU中构建的 prebuild确保符号版本不超过限制checksum mismatch下载的 Release 资产与 pinned 哈希不一致或缓存被篡改删除本地缓存目录后重试并核对 release.json 中的 SHA-256Missing compatible better-sqlite3 artifact缓存缺失或未通过校验重新触发 beforePack 下载检查网络与 Release 可用性Packaged better-sqlite3 artifact is missingafterPack 阶段包内目标路径不存在确认 electron-builder 完成正常 rebuild且resources/app.asar.unpacked未在配置中被排除小结Cherry Studio 的 Linux 打包方案用固定版本预编译产物 多级校验解决了原生模块在 Linux 分发中的两大难题ABI 匹配与旧发行版兼容性。整个链路before-pack.js → download.js → compat.js → after-pack.js以失败即中断的强校验策略确保任何缺失、过期或不兼容的better_sqlite3.node都无法混入安装包。维护者只需遵循先发 Release、再更新 release.json、绝不指向 latest的约定即可安全地随 Electron 与 better-sqlite3 的版本升级持续交付可复现的 Linux 产物。【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cherry Studio Linux 打包全指南：基于 pinned better-sqlite3 预编译产物的构建、校验与更新流程
Cherry Studio Linux 打包全指南基于 pinned better-sqlite3 预编译产物的构建、校验与更新流程【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio本指南聚焦 Cherry Studio 在 Linux 平台上的打包机制Linux 安装包AppImage / deb / rpm依赖从固定版本 Release 下载的 x64 与 ARM64better-sqlite3预编译产物prebuild并通过 beforePack / afterPack 钩子完成下载、校验与替换。读完本文你将掌握 Cherry Studio Linux 打包的完整命令、三步校验管线下载校验、electron-builder 原生依赖重建、打包后替换校验的实现细节以及当 Electron 或 better-sqlite3 升级时如何正确更新 pinned prebuild。背景为什么 Linux 包需要 pinned prebuildCherry Studio 使用 SQLite 存储本地数据而 better-sqlite3版本 12.11.1是包含 C 原生代码的 Node 插件。Electron 运行时自带的 V8/ABI 与系统 Node 不同任何 ABI 不匹配的原生模块都会在启动时崩溃。此外在打包机上现场编译原生模块往往产生对较新 GLIBC/GLIBCXX 的依赖导致产物在较老发行版如 CentOS 7、Ubuntu 18.04 系列上无法加载。为此Cherry Studio 采用固定版本pinned的预编译产物方案所有 Linux 安装包统一使用来自独立仓库CherryHQ/cherry-studio-better-sqlite3的 GitHub Release 中的better-sqlite3prebuild。该方案的核心约束记录在 release.json绝不指向浮动的latestRelease每次构建都锚定一个带版本号的精确 tag每个架构的 addon.node文件和 manifest.manifest.json都附带硬编码的 SHA-256 值Release 元数据Electron 版本、Electron ABI、better-sqlite3 版本必须与当前仓库实际安装的依赖完全一致否则构建直接失败。以当前仓库为例pinned 信息为Electron41.8.0、Electron ABI145、better-sqlite312.11.1Release tag 为better-sqlite3-v12.11.1-electron-v41.8.0-r1。构建命令与前置条件基础构建命令Cherry Studio 的 Linux 构建命令定义在 package.json 的scripts字段中# 同时构建 x64 与 arm64 两个架构 pnpm build:linux # 只构建单一架构 pnpm build:linux:x64 pnpm build:linux:arm64底层展开逻辑以build:linux为例dotenv pnpm run build electron-builder --linux --x64 --arm64即先执行完整的应用构建typecheckelectron-vite build utility process 构建再调用 electron-builder 针对 Linux 目标产出安装包。当前 electron-builder.yml 中 Linux 目标包括 AppImage、deb、rpm 三种格式产物命名形如${productName}-${version}-${arch}.${ext}。首次构建需要网络prebuild 缓存目录为scripts/linux-native/prebuilt/已被 Git 忽略不会入库。首次构建时beforePack钩子会发现缓存为空自动从 pinned GitHub Release 下载对应架构的.node与.manifest.json文件只有下载并验证通过后才写入缓存供后续构建复用。因此首次构建必须能访问 GitHub Release且网络环境需要能连通github.com。不需要 Docker / QEMUCherry Studio 自身的 Linux 打包不依赖 Docker 或 QEMU在 x64 主机上可以直接产出 arm64 安装包因为真正的原生二进制不是现场编译而是从预编译 Release 获取。Docker/QEMU 仅在需要从独立仓库发布新 prebuild 时才派上用场——那是维护者发布预编译产物时的工具与应用打包流程无关。相关环境约束从源码可以补充确认的几点前提包管理器为 pnpmpackageManager: pnpm11.8.0Node 版本约束为24.11.1 24.16.0见 package.json若同时打包多个架构electron-builder 的--x64 --arm64会分别触发两次打包流水线每次对应一个架构中国区构建走独立的build:linux:cn/build:linux:x64:cn/build:linux:arm64:cn使用 electron-builder.cn.config.cjs 作为配置但 Linux prebuild 校验与替换逻辑一致。打包流水线三步校验与替换整个 Linux 打包过程由 electron-builder.yml 中声明的两个钩子驱动beforePack: scripts/before-pack.js afterPack: scripts/after-pack.js第一步beforePack 下载并校验 pinned 产物before-pack.js 在应用文件拷贝进包之前执行。对于 Linux 平台它调用 download.js 的ensureLinuxNativeArtifact完成以下工作架构白名单检查仅接受x64/arm64其他架构直接报Unsupported Linux architectureRelease 元数据一致性校验assertReleaseMetadata将 release.json 中的electronVersion、electronAbi、betterSqlite3Version与当前仓库node_modules中实际安装的版本逐一比对通过 compat.js 的readProjectBuildMetadata读取并用node-abi解析当前 Electron 版本对应的 ABI 号任一字段不匹配即抛出field ... is stale错误并在下载前终止构建缓存复用或原子下载若scripts/linux-native/prebuilt/arch/下已存在通过完整校验的产物直接复用cached: true否则使用curl -fSL --retry 3 --connect-timeout 15 --max-time 120下载 addon 与 manifest 到临时目录逐字节校验 SHA-256 后原子替换缓存目录临时目录 rename避免半成品文件下载后完整校验verifyReleaseArtifact同时校验 pinned 的 Release 资产哈希与产物自身的原生兼容性详见下文第二步的校验项。成功后会打印类似日志Downloaded GLIBC-compatible better-sqlite3 for linux-x64 (sha256)第二步electron-builder 常规原生依赖重建下载校验通过后electron-builder 继续执行其常规的原生依赖重建流程。这里有一个值得注意的设计非 Linux 平台macOS / Windows走的是electron/rebuild从源码强制重编译better-sqlite3buildFromSource: true见 before-pack.js 的prepareNativeModulesForElectron而Linux 平台跳过源码编译、直接使用预编译产物——这正是better-sqlite3编译产物兼容性问题只在 Linux 上突出的原因也是本套方案存在的意义。第三步afterPack 校验并替换打包产物打包完成后after-pack.js 对 Linux 平台调用 compat.js 的replacePackagedBetterSqlite3将缓存的 prebuild 覆盖到包内目标路径resources/app.asar.unpacked/node_modules/better-sqlite3/build/Release/better_sqlite3.node替换前、替换后都会执行verifyNativeArtifact的六项校验全部通过才允许继续校验项实现位置说明Manifest schema 版本compat.jsschemaVersion必须为 2、platform必须为linux关键字段一致性同上arch、electronVersion、electronAbi、betterSqlite3Version必须与当前项目构建元数据一致ELF 架构detectElfArch校验魔数\x7fELF、64 位、小端且e_machine为 62x64或 183arm64ABI 版本上限assertVersionRequirements从二进制文本中解析所有GLIBC_/GLIBCXX_/CXXABI_符号版本取每个 family 的最大值不得超过上限glibc 2.28、glibcxx 3.4.25、cxxabi 1.3.11文件哈希sha256比对产物实际哈希必须与 manifest 记录的sha256一致Manifest 与产物一致性JSON.stringify比对manifest 中的requirements必须与产物解析出的版本要求完全一致替换时还通过fs.copyFileSyncchmodSync保持可执行权限位并对包内落盘文件再做一次完整校验防止打包过程引入损坏字节。任何一项失败都会抛出异常并中断打包——缺失、过期或与 ABI/架构不兼容的产物都不允许进入最终安装包。日志示例Installed GLIBC-compatible better-sqlite3 for linux-x64 at path (ABI 145, {glibc:2.28,...})测试覆盖该流程有完善的单测佐证见 linux-native.test.tsparseVersionRequirements对同一 ABI family 取最高版本号兼容产物通过校验x64 / arm64 各测一次而要求GLIBC_2.29的产物被拒绝错误架构、过期元数据、被篡改的字节均被拒绝分别报manifest field arch、manifest field electronVersion、checksum mismatchensureLinuxNativeArtifact首次下载、二次复用缓存且不再发起网络请求Release 元数据过期时在下载前即失败pinned Release 配置与当前仓库构建输入完全匹配且 tag 不含latest。更新 Prebuild 的完整步骤当Electron 版本升级或better-sqlite3 版本升级时旧 prebuild 将无法通过第一步的元数据一致性校验assertReleaseMetadata构建会以field ... is stale直接失败。此时需要按文档与源码约定的流程更新步骤 1从 prebuild 仓库发布已验证的 Release在独立的CherryHQ/cherry-studio-better-sqlite3仓库中针对新的 Electron / better-sqlite3 组合分别构建并发布 x64、arm64 的addon 文件better_sqlite3-better-sqlite3版本-electron-electron版本-linux-arch.nodemanifest 文件better_sqlite3-better-sqlite3版本-electron-electron版本-linux-arch.manifest.jsonmanifest 内需记录schemaVersion: 2、platform: linux、arch、electronVersion、electronAbi、betterSqlite3Version、sha256以及解析出的requirements见 compat.js 的校验契约。发布新 prebuild 的过程才需要 Docker / QEMU 等交叉编译与验证工具。步骤 2更新 release.json 的固定信息编辑 release.json同步更新{ schemaVersion: 1, repository: CherryHQ/cherry-studio-better-sqlite3, tag: better-sqlite3-vnew-version-electron-vnew-version-r1, metadata: { electronVersion: 新的 Electron 版本, electronAbi: 新的 ABI 号, betterSqlite3Version: 新的 better-sqlite3 版本 }, artifacts: { x64: { addon: { name: better_sqlite3-新版本-electron-新版本-linux-x64.node, sha256: 64 位十六进制哈希 }, manifest: { name: ..., sha256: ... } }, arm64: { /* 同上 */ } } }更新时需同时满足 download.js 中的格式约束repository必须匹配owner/repo形式、schemaVersion必须为 1、tag/metadata/artifacts三要素齐全、资产名只允许[A-Za-z0-9_.-]、sha256必须为 64 位小写十六进制。仓库中的测试linux-native.test.ts 的pinned Linux native release用例会校验release.json与仓库当前构建输入一致因此升级依赖后必须同步更新该文件否则 CI 与本地构建都会失败。规则红线禁止指向 floating latest文档明确强调Never point application builds at a floatinglatestRelease。这有两层含义release.json 的tag必须是精确的版本 tag测试中也有expect(config.tag).not.toContain(latest)的断言语义上应用构建的可复现性优先于总是拿到最新版——如果指向latest同一份代码在不同时间构建可能得到行为不同的二进制且无法追溯、无法回滚。常见问题速查现象原因处理首次构建卡在下载阶段scripts/linux-native/prebuilt/缓存为空需要访问 GitHub Release确认网络可达github.com重跑构建成功后缓存可复用field electronVersion is stale或 ABI / better-sqlite3 字段升级了 Electron 或 better-sqlite3但 release.json 未同步按上文更新 Prebuild流程发布新 Release 并更新release.jsonGLIBC_2.29 ... exceeding the 2.28 limit预编译产物在过新的系统上编译引入了过高 ABI 依赖更换在受控环境Docker/QEMU中构建的 prebuild确保符号版本不超过限制checksum mismatch下载的 Release 资产与 pinned 哈希不一致或缓存被篡改删除本地缓存目录后重试并核对 release.json 中的 SHA-256Missing compatible better-sqlite3 artifact缓存缺失或未通过校验重新触发 beforePack 下载检查网络与 Release 可用性Packaged better-sqlite3 artifact is missingafterPack 阶段包内目标路径不存在确认 electron-builder 完成正常 rebuild且resources/app.asar.unpacked未在配置中被排除小结Cherry Studio 的 Linux 打包方案用固定版本预编译产物 多级校验解决了原生模块在 Linux 分发中的两大难题ABI 匹配与旧发行版兼容性。整个链路before-pack.js → download.js → compat.js → after-pack.js以失败即中断的强校验策略确保任何缺失、过期或不兼容的better_sqlite3.node都无法混入安装包。维护者只需遵循先发 Release、再更新 release.json、绝不指向 latest的约定即可安全地随 Electron 与 better-sqlite3 的版本升级持续交付可复现的 Linux 产物。【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考