Cherry Studio 开发环境搭建与本地调试完整指南(Node.js / pnpm / Electron)
人工智能大模型AI 应用交互助手本地部署【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址https://gitcode.com/CherryHQ/cherry-studio点击查看免费下载本文基于 CherryHQ/cherry-studio 官方开发者文档 docs/contrib/development.md 展开完整覆盖 IDE 配置、Windows 符号链接支持、依赖安装、开发实例数据隔离、调试、测试与多平台构建全流程并深入源码级细节如CS_DEV_USER_DATA_SUFFIX校验逻辑、better-sqlite3预编译流程验证每个环节的真实行为帮助开发者在 Windows / macOS / Linux 上从零跑通 Cherry Studio 的开发、调试与打包。准备工作了解项目技术栈Cherry Studio 是一个 Electron TypeScript 桌面客户端支持多 LLM 提供商。在开始搭建环境前建议先了解仓库的整体结构主进程代码位于 src/main包括 AI 运行时src/main/ai、数据层src/main/data、IPCsrc/main/ipc与核心生命周期src/main/core渲染进程代码位于 src/renderer包含pages、components、composer等目录预加载脚本位于 src/preload通过contextBridge暴露安全的 IPC 接口本地数据库采用better-sqlite3 Drizzle ORM迁移脚本位于 migrations/sqlite-drizzle工具链基于electron-vite、Biome格式化/Lint、oxlint/eslintLint、Vitest单元测试与 PlaywrightE2E。完整脚本命令可查看 package.json 的scripts字段本文涉及的dev、debug、test、build:*均在其中定义。IDE 配置VS Code 及其兼容编辑器任何 VS Code 兼容的编辑器如 Cursor均可直接开发。项目在.vscode/extensions.json中声明了推荐扩展VS Code 打开项目时会提示一键安装扩展 ID用途dbaeumer.vscode-eslintESLint 支持editorconfig.editorconfigEditorConfig 风格统一lokalise.i18n-allyi18n 国际化文件编辑辅助bradlc.vscode-tailwindcssTailwind CSS 智能提示vitest.explorerVitest 测试用例运行/调试面板oxc.oxc-vscodeoxc 解析器支持对应 oxlintbiomejs.biomeBiome 格式化与 Lint同时.vscode/settings.json与.vscode/launch.json已内置项目级工作区配置与调试启动项可直接配合pnpm dev使用。ZedZed 用户按以下步骤配置安装两个扩展Biomebiomejs/biome-zed与oxcoxc-project/zed-oxc复制示例配置文件到本地 Zed 配置cp .zed/settings.json.example .zed/settings.json按需自定义.zed/settings.json该文件已被 git 忽略不会污染仓库。示例文件.zed/settings.json.example展示了 Cherry Studio 的 Zed 推荐配置对 JSON / JSONC 启用 Biome 作为 formatter 并在保存时执行source.fixAll.biome修复对 TSX / TypeScript 在保存时依次执行 Biome、ESLint、oxc 的fixAll以及source.organizeImports.biome并显式指定 Biome 读取仓库根目录的 biome.jsonc 配置文件。这些配置与pnpm format/pnpm lint的脚本行为保持一致保证在编辑器和 CI 中产出相同的代码风格。Windows启用符号链接支持项目使用符号链接symlink同步AGENTS.md、skills等文件。Windows 开发者必须在 clone 之前启用符号链接支持否则这些文件将以普通副本或缺失状态存在影响后续开发启用开发者模式设置 → 更新和安全 → 开发者选项 → 打开“开发人员模式”或通过secpol.msc本地安全策略为当前用户授予SeCreateSymbolicLinkPrivilege创建符号链接权限配置 Gitgit config --global core.symlinks true克隆或重新克隆仓库由于符号链接在 clone 时按配置展开必须先完成第 1、2 步再 clone。若已在未开启符号链接时 clone需要重新克隆仓库才能生效。在非 Windows 平台macOS / Linux上符号链接默认可用无需此步骤。环境要求与工具链安装Node.js版本以.node-version为准项目要求的 Node.js 版本记录在 .node-version当前为24.11.1并在 package.json 的engines.node字段中约束了兼容区间24.11.1 24.16.0。推荐使用 nvm 或 fnm 自动读取版本nvm installpnpm版本由packageManager锁定pnpm 版本锁定在 package.json 的packageManager字段如pnpm11.8.0sha512...。启用 corepack 后pnpm 会自动切换到该精确版本corepack enable安装依赖pnpm install安装过程会触发postinstall钩子构建工作区包cherrystudio/dsh-bridgeprepare钩子还会安装 prek 钩子用于 Git blame 忽略等并写入.git-blame-ignore-revs配置。环境变量文件cp .env.example .env.env.example 中预置了常用变量NODE_OPTIONS--max-old-space-size8000加大 Node 堆内存以应对大型构建、API_KEY/BASE_URL/MODEL开发期默认模型端点、CSLOGGER_MAIN_LEVEL/CSLOGGER_RENDERER_LEVEL主进程与渲染进程日志级别等。启动开发实例pnpm dev 与数据目录隔离基础启动pnpm dev从 package.json 可以看到dev脚本的完整链路pnpm rebuild:electron通过electron-rebuild --force --only better-sqlite3重建原生模块→pnpm download:binaries下载本地模型等二进制见 scripts/download-binaries.js→pnpm run build:utility-process构建 utility process配置见 electron.vite.entries.config.ts→dotenv electron-vite dev。开发数据目录隔离默认情况下开发运行会在 Electron 默认userData目录后追加Dev后缀将开发数据与打包后的应用数据完全隔离。例如打包应用数据目录为…/CherryStudio时开发实例为…/CherryStudioDev。需要同时运行多个开发实例例如对比不同分支、多开测试时为每个实例指定唯一后缀可在.env中配置CS_DEV_USER_DATA_SUFFIXDevQuito或启动时内联传入CS_DEV_USER_DATA_SUFFIXDevQuito pnpm dev CS_DEV_USER_DATA_SUFFIXDevParis pnpm dev后缀校验规则后缀会被拼接到目录名中因此必须是单一路径组件——不允许包含路径分隔符/、\、盘符冒号、Windows 保留字符* ? |、控制字符或结尾的点空白值回退为默认Dev违反上述规则的值会直接终止开发运行而非回退从而保证两个实例永远不会意外共享同一目录。这一行为有源码与测试双重佐证校验实现在 src/main/core/paths/constants.tsFORBIDDEN_DEV_USER_DATA_SUFFIX正则/[\\/:*?|]|\p{Cc}/u拦截分隔符、保留字符与控制字符同时拒绝以.结尾的值。注释解释了原因分隔符可能使目录规范化回退到打包目录如/../CherryStudio而 Windows 会剥离结尾的点导致CherryStudio.与打包目录CherryStudio别名冲突应用点在 src/main/core/preboot/README.md 有说明日志目录也会同步带上后缀macOS 下为app.getPath(logs) 后缀其他平台为resolveDevUserDataPath()/logs见 constants.ts避免开发日志与正式安装版日志混杂边界情况由测试覆盖例如 src/main/core/paths/tests/constants.test.ts 验证了有效后缀生效、空白回退、/../CherryStudio与非法字符抛错等场景。调试模式pnpm debug该命令会以--inspectNode 调试协议、--sourcemap与--remote-debugging-port9222Chromium 远程调试端口启动。随后在浏览器中打开chrome://inspect即可对主进程与渲染进程进行断点调试、查看调用栈与源码映射。如果使用 VS Code也可以直接使用.vscode/launch.json中预置的调试配置选择对应启动项即可附加调试器。运行测试pnpm testpackage.json 中test脚本串联了多个 Vitest projectmain主进程如 AI 运行时、数据层、renderer渲染进程组件/页面、aiCore、ui、shared、provider-registry、scripts、preload等统一由根目录 vitest.config.ts 组织。pretest钩子会先执行pnpm rebuild:node重建better-sqlite3原生绑定确保原生模块与当前 Node 版本匹配。常用变体pnpm test:main/pnpm test:renderer单独运行主进程或渲染进程测试pnpm test:watch监听模式pnpm test:e2ePlaywright E2E配置见 playwright.config.ts。构建与打包# Windows pnpm build:win # macOS pnpm build:mac # Linux pnpm build:linux从 package.json 可见build脚本会先执行pnpm run typecheckTypeScript 类型检查再以electron-vite build构建主进程与渲染进程随后构建 utility processbuild:*系列脚本再调用 electron-builder 产出对应平台安装包并支持架构细分命令例如Windowsbuild:winx64 arm64、build:win:x64、build:win:arm64macOSbuild:macarm64 x64、build:mac:arm64、build:mac:x64Linuxbuild:linuxx64 arm64、build:linux:x64、build:linux:arm64。另有两类值得留意的构建入口CN 版构建build:win:cn/build:mac:cn/build:linux:cn使用独立的 electron-builder.cn.config.cjs 配置并通过CHERRY_EDITIONcn环境变量区分版本本地解包pnpm build:unpack使用electron-builder --dir生成未打包的目录产物便于快速验证。架构相关命令与 better-sqlite3 预编译关于架构相关命令与固定的better-sqlite3预编译prebuild工作流详见 docs/contrib/linux-packaging.md核心要点Linux 包使用固定版本pinned的 x64 / ARM64better-sqlite3预编译产物来源是独立的预编译仓库 Release首次构建需要网络访问以填充 git 忽略的scripts/linux-native/prebuilt/缓存目录打包本身不需要 Docker 或 QEMU仅发布新预编译产物时才需要打包流程为beforePack下载目标产物并校验固定 Release 校验和 → electron-builder 常规原生依赖重建 →afterPack校验 Electron ABI、模块版本、ELF 架构、校验和与最大 GLIBC/GLIBCXX/CXXABI 要求后替换打包内的better_sqlite3.node产物缺失、过期或不兼容都会中止打包更新预编译产物时先在预编译仓库发布已校验的 Release再更新 scripts/linux-native/release.json 中的精确 tag、文件名、元数据与 SHA-256且不得指向浮动的latestRelease。常见问题排查速查现象可能原因处理方式Windows 下 clone 后 skills / AGENTS.md 缺失未启用符号链接支持按上文开启开发者模式并git config --global core.symlinks true后重新 clonepnpm dev报 Node 版本错误Node 版本不在engines区间使用 nvm/fnm 按 .node-version 安装24.11.1原生模块加载失败better-sqlite3二进制与 Electron ABI 不匹配执行pnpm rebuild:electron或重新pnpm install多个开发实例数据互相污染未设置唯一后缀为每个实例设置不同的CS_DEV_USER_DATA_SUFFIX启动即抛错提示后缀非法后缀含分隔符/保留字符/结尾点改用单一合法路径组件如DevQuito延伸阅读docs/contrib/linux-packaging.mdLinux 打包与better-sqlite3预编译工作流docs/contrib/branching-strategy.md分支与版本管理策略docs/contrib/release-workflow.md发布流程docs/contrib/test-plan.md测试计划与覆盖要求docs/contrib/development.md本文的官方原始文档。赞分享人工智能大模型AI 应用交互助手本地部署【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址https://gitcode.com/CherryHQ/cherry-studio点击查看免费下载相关推荐Devon开发环境本地搭建与调试指南Devon开发环境本地搭建与调试指南 前言 还在为复杂的AI编程助手搭建而头疼Devon作为开源结对编程工具提供了从终端界面到图形界面的完整开发体验。本文WebDataset与自然语言处理构建高效文本数据加载管道WebDataset与自然语言处理构建高效文本数据加载管道 WebDataset是一个基于Python的高性能I/O系统专为大型和小型深度学习问题设计如何快速搭建jsDelivr开发环境完整本地开发与调试指南jsDelivr作为全球领先的开源CDN服务为开发者提供了免费、快速、可靠的静态资源加速服务。本文将详细介绍如何搭建jsDelivr开发环境包括本地开发配置创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考

相关新闻

PyTorch C++ 前端(LibTorch)MNIST 手写数字识别:从 CMake 构建到训练源码全解析

PyTorch C++ 前端(LibTorch)MNIST 手写数字识别:从 CMake 构建到训练源码全解析

示例工程人工智能深度学习 【免费下载链接】examples A set of examples around pytorch in Vision, Text, Reinforcement Learning, etc. 项目地址: https://gitcode.com/gh_mirrors/ex/examples 点击查看 免费下载 本示例(仓库 cpp/mnist)…

2026/11/20 19:25:23 阅读更多 →
氢能在综合能源系统中的建模与优化实践

氢能在综合能源系统中的建模与优化实践

1. 氢能在综合能源系统中的角色定位去年参与某工业园区微电网项目时,我第一次真切感受到氢能作为能源载体的独特价值。当光伏发电量在午间达到峰值时,电解水制氢设备自动启动,将多余电能转化为氢能储存;到了晚间负荷高峰时段&…

2026/11/1 0:06:12 阅读更多 →
CatmiSteam:Steam游戏资产本地化治理系统解析

CatmiSteam:Steam游戏资产本地化治理系统解析

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/11/21 8:46:59 阅读更多 →

最新新闻

Electron桌面应用开发实战:从环境搭建到打包发布全流程

Electron桌面应用开发实战:从环境搭建到打包发布全流程

做前端这些年,我大部分时间都在跟浏览器标签页打交道,直到第一次把桌面应用跑起来,才发现原来自己一直被限制在地址栏和刷新按钮围起来的框框里。Electron这个词,最开始是在某段时间频繁出现在同事的讨论里,一个用HTML…

2026/11/20 23:27:28 阅读更多 →
滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

简介:亚太天能T109滑盖智能锁产品说明书是一份PDF格式的官方技术文档,主要面向智能锁安装人员、终端用户及售后维护者,帮助快速掌握产品安装、配置与常见故障处理。全包仅1个PDF文件,大小4.37MB,内容结构清晰&#xff…

2026/11/20 23:27:28 阅读更多 →
PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

上个月我在调试一台高速AGV的驱动系统,整车要求空载跑到8m/s,电机转速已经拉到额定点,驱动器的输出电压也顶到了母线电压极限附近。再往上踩速度指令,转速纹丝不动,三相电流反而开始震荡。那会儿我的第一反应就是&…

2026/11/20 23:27:28 阅读更多 →
C++核心知识点:从内存管理到STL的实战指南

C++核心知识点:从内存管理到STL的实战指南

C 这门语言我前前后后折腾了十几年,用它写过嵌入式驱动、做过游戏服务端,也搭过基础组件库。每次看到新人一头扎进"C 核心知识点"这个搜索词,我其实挺感慨的——这门语言的难点从来不是语法多,而是知识点之间的耦合太深…

2026/11/20 21:55:32 阅读更多 →
T109滑盖智能锁怎么装?安装调试与故障排查全攻略

T109滑盖智能锁怎么装?安装调试与故障排查全攻略

简介:亚太天能T109滑盖智能锁产品说明书以PDF格式发布,适合智能锁用户、安装人员与售后维修人员阅读。内容围绕T109系列指纹密码刷卡锁展开,先介绍前面板、后面板、锁体、机械钥匙、电池盒盖等部件名称与功能,再给出完整安装步骤&…

2026/11/20 23:27:28 阅读更多 →
LLM知识降熵:从信息垄断到理解权下放

LLM知识降熵:从信息垄断到理解权下放

你有没有过这种经历:翻开源码注释、论文摘要或者一份专业报告,每个字都认识,连在一起却像天书。想找人聊聊,身边要么没人懂,要么懂的懒得跟你解释。后来我试着把同一段内容丢给一个大语言模型,几秒钟之后&a…

2026/11/20 22:59:12 阅读更多 →

日新闻

周新闻

月新闻