Cherry Studio编译构建：从源码到可执行文件

【免费下载链接】cherry-studio 🍒 Cherry Studio is a desktop client that supports for multiple LLM providers. Support deepseek-r1 项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio

概述

Cherry Studio是一款支持多LLM（Large Language Model，大语言模型）提供商的桌面客户端，特别支持deepseek-r1模型。本文将详细介绍如何从源码编译构建Cherry Studio，涵盖环境准备、依赖管理、构建配置和打包发布的全流程。

环境准备

系统要求

操作系统	版本要求	架构支持
Windows	Windows 10+	x64, ARM64
macOS	macOS 11.0+	x64, ARM64
Linux	Ubuntu 18.04+	x64, ARM64

开发工具链

# 安装Node.js和npm（推荐使用nvm管理版本）
curl -o- https://cdn.npmmirror.com/binaries/node/v18.17.0/install.sh | bash
nvm install 18
nvm use 18

# 安装Rust工具链（如果使用Rust后端）
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
rustup default stable

# 安装Python 3.8+
sudo apt update && sudo apt install python3 python3-pip

构建依赖

# 前端依赖
npm install -g pnpm yarn

# 桌面端框架依赖（假设使用Electron或Tauri）
npm install -g electron-builder
# 或
cargo install tauri-cli

# 系统开发工具
sudo apt install build-essential libgtk-3-dev libwebkit2gtk-4.0-dev

项目结构分析

构建流程详解

1. 依赖安装

# 克隆项目
git clone https://gitcode.com/gh_mirrors/ch/cherry-studio.git
cd cherry-studio

# 安装前端依赖
pnpm install  # 或 npm install / yarn install

# 安装Rust依赖（如果适用）
cargo fetch

2. 开发环境构建

# 启动开发服务器
pnpm dev

# 或使用特定构建命令
pnpm build:dev

# 监控文件变化自动重建
pnpm watch

3. 生产环境构建

# 构建生产版本
pnpm build

# 平台特定构建
pnpm build:win    # Windows版本
pnpm build:mac    # macOS版本  
pnpm build:linux  # Linux版本

# 构建并打包安装程序
pnpm dist

构建配置解析

package.json关键配置

{
  "scripts": {
    "dev": "vite",
    "build": "vite build && electron-builder",
    "build:win": "vite build && electron-builder --win",
    "build:mac": "vite build && electron-builder --mac",
    "build:linux": "vite build && electron-builder --linux",
    "dist": "electron-builder --publish=never"
  },
  "devDependencies": {
    "electron": "^25.0.0",
    "electron-builder": "^24.0.0",
    "vite": "^4.0.0",
    "typescript": "^5.0.0"
  }
}

构建配置文件

// vite.config.ts
import { defineConfig } from 'vite'
import electron from 'vite-plugin-electron'

export default defineConfig({
  plugins: [
    electron({
      main: {
        entry: 'src/main.ts',
      },
      preload: {
        input: 'src/preload.ts',
      },
    })
  ],
  build: {
    target: 'es2020',
    minify: 'esbuild',
  }
})

多平台构建策略

Windows平台构建

# 设置Windows构建环境
export npm_config_platform=win32
export npm_config_arch=x64

# 构建Windows安装包
pnpm build:win

# 生成文件：
# - dist/cherry-studio Setup 1.0.0.exe
# - dist/latest.yml

macOS平台构建

# 需要在macOS系统上执行
export npm_config_platform=darwin
export npm_config_arch=arm64  # 或 x64

pnpm build:mac

# 生成文件：
# - dist/cherry-studio-1.0.0.dmg
# - dist/cherry-studio-1.0.0.zip

Linux平台构建

# Linux构建配置
export npm_config_platform=linux
export npm_config_arch=x64

pnpm build:linux

# 生成文件：
# - dist/cherry-studio-1.0.0.AppImage
# - dist/cherry-studio_1.0.0_amd64.deb

高级构建配置

代码签名配置

// electron-builder.config.js
module.exports = {
  appId: 'com.cherry.studio',
  productName: 'Cherry Studio',
  directories: {
    output: 'dist'
  },
  files: [
    'dist-electron/**/*',
    'dist/**/*'
  ],
  mac: {
    category: 'public.app-category.productivity',
    icon: 'build/icon.icns',
    target: 'dmg'
  },
  win: {
    target: 'nsis',
    icon: 'build/icon.ico'
  },
  linux: {
    target: 'AppImage',
    icon: 'build/icon.png'
  },
  // 代码签名配置
  sign: async (config) => {
    // 自动签名逻辑
  }
}

环境变量管理

# 环境配置文件 .env
VITE_APP_VERSION=1.0.0
VITE_API_BASE_URL=https://api.cherry-studio.com
VITE_LLM_PROVIDERS=openai,deepseek,anthropic

# 构建时注入环境变量
VITE_LLM_PROVIDERS=openai,deepseek pnpm build

构建优化策略

1. 依赖树优化

# 分析包大小
pnpm run build --report

# 使用webpack-bundle-analyzer
npm install -g webpack-bundle-analyzer
webpack-bundle-analyzer dist/report.html

2. 代码分割配置

// vite.config.ts 优化配置
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom'],
          llm: ['openai', 'anthropic-js'],
          utils: ['lodash', 'date-fns']
        }
      }
    }
  }
})

3. 性能监控配置

// 构建性能监控
const { performance } = require('perf_hooks')

const start = performance.now()
// 构建过程
const end = performance.now()
console.log(`构建耗时: ${(end - start).toFixed(2)}ms`)

常见问题解决

构建错误排查表

错误类型	症状描述	解决方案
依赖冲突	npm ERR! ERESOLVE unable to resolve dependency tree	使用 npm install --legacy-peer-deps
内存不足	JavaScript heap out of memory	设置 NODE_OPTIONS=--max_old_space_size=4096
权限问题	EACCES: permission denied	使用 sudo 或修复目录权限
网络超时	ETIMEDOUT connection timed out	配置镜像源或使用代理

平台特定问题

# Windows构建问题
# 错误：无法找到rc.exe
# 解决方案：安装Windows SDK

# macOS代码签名问题  
# 错误：No identity found
# 解决方案：配置有效的开发者证书

# Linux依赖问题
# 错误：libgtk-3.so.0: cannot open shared object file
# 解决方案：安装系统依赖包

持续集成配置

GitHub Actions示例

name: Build and Release

on:
  push:
    tags: ['v*']

jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '18'
        cache: 'pnpm'
    
    - name: Install dependencies
      run: pnpm install
      
    - name: Build application
      run: pnpm build
      
    - name: Create release
      uses: softprops/action-gh-release@v1
      with:
        files: dist/*

最佳实践总结

1. 版本管理策略

# 语义化版本控制
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin --tags

# 自动版本号递增
npm version patch  # 1.0.0 → 1.0.1
npm version minor  # 1.0.1 → 1.1.0  
npm version major  # 1.1.0 → 2.0.0

2. 构建缓存优化

# 配置构建缓存
export npm_config_cache=$HOME/.npm
export CARGO_HOME=$HOME/.cargo

# 使用构建缓存工具
npm install -g turbo
turbo build

3. 安全构建实践

# 依赖安全检查
npm audit
pnpm audit
cargo audit

# 许可证检查
npx license-checker

结语

Cherry Studio的编译构建流程体现了现代桌面应用开发的最佳实践。通过合理的项目结构设计、多平台构建支持和持续集成配置，开发者可以高效地构建和发布高质量的LLM桌面客户端。

掌握这些构建技术不仅有助于Cherry Studio的开发，也为其他类似项目的构建提供了可复用的模式和解决方案。随着项目的不断发展，构建流程也需要持续优化以适应新的需求和技术变化。

【免费下载链接】cherry-studio 🍒 Cherry Studio is a desktop client that supports for multiple LLM providers. Support deepseek-r1 项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio