3步精通FreeShow架构：从核心模块到部署的全流程解析

一、核心架构：理解FreeShow的模块组成

功能导览：揭示FreeShow的三大核心模块（前端界面/后端服务/数据处理），掌握项目的整体技术架构🔍

1.1 前端交互层：打造沉浸式用户体验

FreeShow的前端代码集中在src/frontend/目录，采用Svelte框架构建响应式界面。核心模块包括：

• 组件系统（components/）：如幻灯片编辑器（Slide.svelte）、媒体播放器（Video.svelte）等可视化组件
• 状态管理（stores.ts）：通过响应式变量实现界面与数据的实时同步⚡
• 交互逻辑（utils/）：处理键盘快捷键、拖拽操作等用户行为

新手误区：混淆frontend/components与server/components目录，前者用于桌面端UI，后者为远程控制界面组件。

图1：FreeShow启动界面展示了左侧媒体库、中间幻灯片编辑区和右侧预览窗口的三栏布局

1.2 后端服务层：驱动功能实现的引擎

后端代码位于src/electron/，基于Electron框架实现跨平台能力：

• IPC通信（IPC/main.ts）：处理主进程与渲染进程的消息传递
• 媒体处理（audio/、output/）：实现音频混合、视频输出等核心功能🎵
• 外部集成（contentProviders/）：对接Canva、PlanningCenter等第三方内容平台

1.3 数据管理层：保障项目稳定运行

数据处理核心模块分布在：

• 存储系统（src/electron/data/）：处理项目保存（save.ts）、备份（backup.ts）和导入导出（import.ts/export.ts）
• 配置管理（config/）：包含构建配置（electron-builder.yaml）和类型定义（tsconfig.*.json）📦
• 类型定义（src/types/）：通过TypeScript接口规范数据结构，如Show.ts定义演示文稿格式

二、启动逻辑：从代码到界面的运行流程

功能导览：解析FreeShow的启动链条，理解前后端如何协同工作🔍

2.1 启动入口：多环境适配的脚本设计

项目启动脚本位于scripts/start.js，核心逻辑包括：

// 简化版启动流程
const { app } = require('electron')
app.whenReady().then(() => {
  createMainWindow()  // 创建主窗口
  loadFrontendAssets() // 加载Svelte构建产物
  initializeServices() // 启动后端服务
})

• 开发环境：通过vite.config.mjs启动热重载服务器
• 生产环境：使用electron-builder打包为可执行文件

2.2 前后端联动时序

1. 主进程启动（src/electron/index.ts）：初始化窗口和服务
2. 渲染进程加载（public/index.html）：加载Svelte应用
3. IPC握手：通过frontend/IPC/main.ts建立通信通道
4. 数据加载：从本地存储读取最近项目列表📊

2.3 服务启动验证

可通过以下命令检查启动状态：

# 开发模式启动
npm run dev
# 检查服务端口
netstat -tulpn | grep 3000

三、配置体系：定制FreeShow的运行环境

功能导览：掌握配置文件的使用方法，实现个性化部署🔍

3.1 环境变量配置（.env）

创建.env文件配置敏感信息：

# 示例模板
APP_NAME=FreeShow
API_KEY=your_api_key_here
MAX_UPLOAD_SIZE=50MB

• 必配项：NODE_ENV（development/production）
• 选配件：第三方服务API密钥、日志级别等

3.2 构建配置详解

核心配置文件位于config/building/：

• electron-builder.yaml：定义打包参数（如窗口大小、图标路径）
• vite.config.servers.mjs：配置Vite开发服务器⚙️
• snapcraft.yaml：Linux snap包构建规则

3.3 package.json关键脚本

{
  "scripts": {
    "dev": "node scripts/start.js",       // 开发启动
    "build": "node scripts/preBuild.js && electron-builder", // 生产构建
    "test": "playwright test"             // 自动化测试
  }
}

• 使用npm run build -- --linux指定构建平台
• npm run test执行config/testing/目录下的测试用例

结语

通过本文的三阶框架，你已掌握FreeShow的架构设计、启动流程和配置方法。建议从src/frontend/components/slide/Slide.svelte入手，逐步深入核心功能模块，探索开源 presenter 软件的实现奥秘。