1. 简介
目的
Cherry Studio 是一款功能多样、跨平台的桌面客户端，旨在让用户能够便捷地连接和管理来自不同提供商的大型语言模型（LLM）服务 。它支持多种模型来源，包括云服务（如 OpenAI、Gemini、Anthropic）、AI Web 服务（如 Claude、Poe）以及本地模型（通过 Ollama、LM Studio 等）。该应用程序可在 Windows、macOS 和 Linux 操作系统上运行 。
指南焦点
本指南专门面向希望从源代码设置 开发环境 的开发者或技术用户。我们将详细介绍克隆项目仓库、安装必要的依赖项以及在本地运行应用程序的完整步骤。本指南的目标是帮助您快速启动并运行 Cherry Studio 的开发版本，以便进行功能探索、测试或参与项目贡献。本指南不涉及预构建应用程序的安装或高级功能的使用。
目标受众
本指南的目标读者是熟悉基本命令行操作、Git 版本控制系统以及 Node.js 开发环境的开发者或技术爱好者。
预期成果
完成本指南后，用户将能够在本地成功运行 Cherry Studio 的开发模式实例，并了解如何进行必要的初始配置以开始与 LLM 进行对话。
2. 环境准备（先决条件）
概述
为了确保开发环境的顺利搭建并与项目的开发标准保持一致，需要安装特定版本的工具和软件。遵循这些要求可以避免潜在的兼容性问题，并保证构建过程的可复现性。
操作系统
● 数据点： Cherry Studio 可在 Windows、Mac 和 Linux 上使用。
● 说明： 支持主流的桌面操作系统。虽然具体的版本号未在文档中明确提及，但通常建议使用最新稳定版本的 Windows、macOS 或常见的 Linux 发行版（如 Ubuntu、Fedora 等）。
Node.js
● 数据点： 需要安装 Node.js v20.x.x 2。
● 说明： 这是项目运行和构建的关键依赖。必须 使用 Node.js 的 v20 主版本系列。使用其他版本（如 v18 或 v21）可能会导致依赖安装失败或构建错误，因为项目可能依赖于 v20 引入的特定功能或 API。您可以通过在终端运行 $node -v 命令来检查当前的 Node.js 版本。如果版本不符或未安装，请访问 Node.js 官方网站 下载并安装 v20.x.x 版本。
Yarn 包管理器（通过 Corepack）
● 数据点： 项目使用 Yarn 作为包管理器，并通过 Corepack 管理其版本，开发文档明确要求准备 Yarn v4.6.0 2。
● 说明： 项目选择 Yarn 进行依赖管理，并通过 Node.js v16.10+ 内置的 Corepack 工具来确保所有开发者使用统一的 Yarn 版本。这种做法至关重要，因为它能有效避免因包管理器版本差异导致的依赖解析不一致、lock 文件冲突以及构建脚本运行失败等常见问题（即所谓的“在我机器上可以运行”问题）。这体现了项目在维护开发环境稳定性方面的成熟实践。安装步骤中包含了启用 Corepack 和设置指定 Yarn 版本的命令，用户无需手动安装 Yarn。
Git
● 数据点： 项目托管在 GitCode 上，安装过程涉及克隆仓库。https://gitcode.com/CherryHQ/cherry-studio
https://gitcode.com/CherryHQ/cherry-studio
● 说明： Git 是获取项目源代码所必需的版本控制系统。如果您尚未安装 Git，请访问 Git 官方网站 下载并安装。您可以通过在终端运行 $git --version 命令来检查 Git 是否已成功安装。
为了方便快速核对，下表总结了搭建 Cherry Studio 开发环境所需的所有先决条件：
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
3. 安装步骤
概述
请按顺序在您的终端（命令行界面）中执行以下命令，以下载 Cherry Studio 的源代码并安装其运行所需的全部依赖项。
步骤 1：克隆仓库
● 数据点： 标准 Git 克隆命令，仓库 URL 来自。
● 说明： 此命令会将 Cherry Studio 的官方代码仓库完整地下载到您的本地计算机。如果您计划为项目贡献代码，通常建议先 Fork 仓库到您自己的 GitCode 账户，然后克隆您 Fork 后的仓库。但如果目的仅仅是在本地运行和测试，直接克隆官方仓库即可。
● 命令：
Bash
git clone https://gitcode.com/CherryHQ/cherry-studio.git步骤 2：进入项目目录
● 数据点： 标准命令行导航操作。
● 说明： 使用 cd 命令切换到刚刚克隆下来的项目文件夹。
● 命令：
Bash
cd cherry-studio步骤 3：启用 Corepack 并设置 Yarn 版本
● 数据点： 命令源自 dev.md 2。
● 说明： 这两个命令用于确保项目使用其指定的 Yarn 版本 (v4.6.0) 。corepack enable 激活 Corepack 功能，yarn set version 4.6.0 则根据项目要求设置当前项目使用的 Yarn 版本。这是保证依赖安装和脚本执行一致性的关键步骤。
● 命令：
Bash
corepack enable
yarn set version 4.6.0步骤 4：安装依赖
● 数据点： yarn install 。
● 说明： 此命令会读取项目根目录下的 yarn.lock 文件，并使用上一步配置好的 Yarn 版本下载并安装所有必需的项目依赖项。这个过程会确保您本地安装的依赖包版本与项目维护者和其他贡献者完全一致。根据您的网络状况和计算机性能，此步骤可能需要几分钟时间。
● 命令：
Bash
yarn install4. 启动项目（开发模式）
概述
成功完成安装步骤后，您可以按照以下说明在本地启动 Cherry Studio 应用程序的开发版本。
命令
● 数据点： yarn dev。
● 说明： 这个命令是启动项目进行本地开发的主要方式。它通常会执行以下操作：编译应用程序代码（通常在内存中）、启动一个本地开发服务器，并打开 Cherry Studio 的应用程序窗口。开发模式通常还包含“热重载”（Hot Reloading）功能，这意味着当您修改并保存项目代码时，应用程序会自动更新，无需手动重启，极大地提高了开发效率。执行命令后，终端会显示一些编译信息，稍等片刻，应用程序界面便会启动。
● 命令：
Bash
yarn dev关于构建命令的说明
● 数据点： yarn build:win, yarn build:mac, yarn build:linux。
● 说明： 请注意，dev.md 文件中提到的 build 相关命令（如 yarn build:win）并非 用于启动开发环境。这些命令用于在开发完成后，为特定的操作系统（Windows、macOS、Linux）创建可分发的应用程序安装包或可执行文件。初学者请勿混淆，运行这些命令不会启动应用程序进行开发或测试。
5. 基本用法示例（首次对话）
概述
首次启动 Cherry Studio 后，需要进行一些基本配置才能开始与 LLM 交互。以下步骤将指导您完成连接到一个模型服务并进行第一次对话的核心流程。
步骤 1：首次启动与配置需求
● 说明： 当 Cherry Studio 应用程序窗口首次出现时，您可能会看到一个欢迎界面或主操作界面。需要明确的是，Cherry Studio 本身是一个客户端，它需要连接到后端的 LLM 服务才能进行智能对话。因此，在进行任何对话之前，必须 先配置至少一个模型服务提供商。
步骤 2：访问模型服务设置
● 数据点： 官方文档在“模型服务配置”下列出了多个提供商 。
● 说明： 在 Cherry Studio 的应用程序界面中，找到相关的设置区域。通常，这部分会标记为“设置”、“偏好设置”、“模型服务”或类似的名称。由于具体的 UI 布局未在参考资料中提供，请根据实际界面查找。
步骤 3：选择并配置提供商
● 数据点： 支持 OpenAI、Gemini、Ollama 等多种服务。
● 说明： 从列表中选择一个您拥有访问权限的模型服务提供商。例如，如果您有 OpenAI API 密钥，可以选择 OpenAI；如果您在本地运行了 Ollama，可以选择 Ollama。配置过程通常需要输入凭据（如 API Key、Secret Key）或指定连接参数（如本地服务的 URL 地址）。请注意： 每个提供商的具体配置步骤各不相同，详细操作超出了本快速入门指南的范围。
● 参考： 关于如何配置 OpenAI、Google Gemini、Ollama 或其他特定提供商的详细说明，请查阅 Cherry Studio 官方文档 的模型服务配置部分：https://docs.cherry-ai.com/pre-basic/providers
步骤 4：开始对话
● 数据点： 核心功能是对话，支持多模型同时对话和 AI 助手。
● 说明： 成功配置并激活至少一个模型服务后，您就可以开始对话了。通常需要：
- 导航到应用程序的“对话”或“聊天”界面。
- （如果配置了多个模型）选择您想要交互的一个或多个模型。Cherry Studio 支持同时向多个模型提问并获取回复。
- 在输入框中键入您的问题或提示，例如输入“你好，世界！”。
- 发送消息（通常通过按 Enter 键或点击发送按钮）。 您应该很快就能看到来自所选 LLM 的回复。您也可以探索一下预设的 AI 助手（超过 300 种），它们可能提供针对特定任务的优化提示。
后续步骤
● 说明： 现在您已经成功在本地运行了 Cherry Studio 并完成了首次对话。建议您进一步探索应用程序的其他功能，例如文件处理、WebDAV 支持、Mermaid 图表、代码高亮、全局搜索、话题管理等。
● 参考： 如需了解所有高级功能、详细配置选项和故障排除信息，请务必查阅完整的 Cherry Studio 官方文档：https://docs.cherry-ai.com。该文档网站是获取最全面、最准确信息的最佳来源，补充了项目仓库中 README 和 dev.md 提供的基础和开发设置信息。
6. 总结
本快速入门指南详细介绍了如何从源代码克隆 Cherry Studio 项目，配置必要的开发环境（包括特定版本的 Node.js 和 Yarn），安装依赖项，并在本地以开发模式启动应用程序。同时，也指导了用户如何在首次启动后配置一个 LLM 服务提供商并进行基础的对话交互。
通过遵循本指南，开发者应能够快速搭建起一个可用的本地开发环境，为进一步探索 Cherry Studio 的功能、进行定制开发或参与社区贡献打下基础。若需深入了解各项功能或遇到问题，请务必参考项目简介 | CherryStudio如果您有兴趣为项目贡献代码，请查阅项目 GitCode 仓库中的贡献指南。
扫一扫
3793
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
