Electron-Liquid-Glass 项目开发指南：从环境搭建到代码提交全流程

项目概述

Electron-Liquid-Glass 是一个结合了 Electron 框架与原生 macOS 视觉效果的创新项目，它实现了类似液态玻璃的炫酷界面效果。作为开发者，理解其技术架构和开发流程对于参与项目至关重要。

开发环境配置

系统要求

由于项目深度集成了 macOS 原生能力，开发环境必须满足以下条件：

• 操作系统：macOS（必须）
• Node.js 18+ 版本
• Bun 包管理器（推荐）
• Xcode 命令行工具

初始化步骤

1. 获取项目代码 使用 Git 克隆项目到本地开发环境：

   git clone 项目仓库地址
   cd electron-liquid-glass
   

2. 安装依赖 推荐使用 Bun 进行依赖管理：

   bun install
   

3. 构建流程 项目包含两个主要构建步骤：

   • 原生模块构建：

     bun run build:native
     

   • TypeScript 库构建：

     bun run build
     

4. 运行示例

   bun run dev
   

开发工作流详解

代码修改规范

1. 分支管理 建议采用功能分支工作流：

   git checkout -b feature/功能名称
   

2. 编码规范

   • 保持与现有代码风格一致
   • 复杂逻辑必须添加注释
   • 及时更新 TypeScript 类型定义

3. 测试验证 修改后应执行完整测试流程：

   bun run build:all
   bun run dev
   

提交信息规范

采用 Conventional Commits 规范，主要类型包括：

• feat: 新增功能
• fix: 错误修复
• docs: 文档更新
• style: 代码样式调整
• refactor: 代码重构
• test: 测试相关
• chore: 维护性任务

代码质量保障

代码风格

• 新代码必须使用 TypeScript
• 遵循 ESLint 规范（如已配置）
• 使用 Prettier 保持代码格式统一
• 公共 API 必须添加 JSDoc 注释

测试策略

• 必须在 macOS 环境下测试
• 尽可能覆盖多版本 Electron
• 同时测试 ESM 和 CJS 模块系统
• 示例应用必须通过测试

原生模块开发指南

C++/Objective-C 规范

1. 命名约定 遵循现有项目的命名风格，保持一致性

2. 错误处理 必须实现完善的错误处理机制

3. UI 线程操作 使用 RUN_ON_MAIN 宏处理 UI 相关操作

4. 私有 API 使用私有 API 时必须添加详细注释说明

构建选项

• 常规构建：

  bun run clean
  bun run build:native
  

• 调试构建（含符号信息）：

  npm run build:native -- --debug
  

发布流程解析

项目采用自动化发布流程，也支持手动发布：

# 补丁版本 (0.1.0 → 0.1.1)
./scripts/release.sh patch

# 次要版本 (0.1.0 → 0.2.0)
./scripts/release.sh minor

# 主要版本 (0.1.0 → 1.0.0)
./scripts/release.sh major

技术要点解析

1. Electron 与原生集成 项目巧妙地将 Electron 的跨平台能力与 macOS 原生视觉效果相结合，实现了独特的液态玻璃效果。

2. 多线程处理 原生模块中需要注意主线程与渲染线程的交互，确保 UI 操作的线程安全。

3. 性能优化 视觉效果实现需要考虑性能影响，避免过度消耗系统资源。

常见问题解决方案

1. 构建失败

   • 检查 Xcode 命令行工具是否安装完整
   • 确认 Node.js 版本符合要求
   • 清理后重新构建

2. 效果异常

   • 验证 macOS 系统版本兼容性
   • 检查 Electron 版本是否匹配
   • 查看原生模块是否正确加载

3. 类型错误

   • 确保 TypeScript 类型定义完整
   • 检查跨语言类型映射是否正确

通过本文的详细指南，开发者可以全面了解 Electron-Liquid-Glass 项目的开发规范和最佳实践，为项目贡献高质量的代码。