🎉 SenseVox Electron 桌面应用 - 从这里开始

欢迎！你的 Next.js 应用现在已经完全支持 Electron 桌面应用了。

⚡️ 30 秒快速启动

# 1. 安装依赖（仅首次）
npm install

# 2. 启动开发模式
npm run app:dev

就是这么简单！🚀

📚 完整文档索引

根据你的需求，选择对应的文档：

🆕 新手入门

ELECTRON_QUICK_START.md ⭐ 强烈推荐先看这个

快速启动指南（3 分钟上手）
开发模式说明
打包应用教程
使用示例代码
常见问题解答

阅读时间: 10 分钟

🔧 遇到安装问题？

INSTALLATION.md

详细安装步骤
网络问题解决方案
常见错误处理
依赖安装故障排查
安装检查清单

阅读时间: 5 分钟

📖 深入开发

README_ELECTRON.md

技术栈详解
项目结构说明
所有脚本详细说明
配置文件解析
开发注意事项

阅读时间: 15 分钟

📊 了解集成内容

ELECTRON_INTEGRATION_SUMMARY.md

集成工作总结
架构说明
功能特性列表
待完成事项
最佳实践

阅读时间: 20 分钟

📝 版本变更

CHANGELOG_ELECTRON.md

详细的变更日志
API 变更说明
迁移指南
兼容性信息

阅读时间: 10 分钟

🔄 准备提交代码？

GIT_COMMIT_GUIDE.md

Git 提交指南
推荐的提交方式
PR 创建模板
提交检查清单

阅读时间: 5 分钟

🎯 常见使用场景

场景 1: 我想马上试试 Electron 应用

# 快速启动（需要网络良好）
npm install
npm run app:dev

👉 遇到问题？查看 INSTALLATION.md

场景 2: 我想在浏览器中开发前端

# 像以前一样开发
npm run dev

访问 http://localhost:3000

说明: Electron 集成完全向后兼容，不影响浏览器开发。

场景 3: 我想打包桌面应用

# macOS
npm run dist:mac

# Windows  
npm run dist:win

# Linux
npm run dist:linux

注意: 首次打包前需要添加应用图标，查看 build/README.md

场景 4: 我想在代码中使用 Electron 功能

// 1. 导入工具函数
import { isElectron, getAppVersion } from '@/lib/electron';

// 2. 检测环境
if (isElectron()) {
  // Electron 环境
  const version = await getAppVersion();
  console.log('应用版本:', version);
} else {
  // 浏览器环境
  console.log('在浏览器中运行');
}

👉 更多示例查看 ELECTRON_QUICK_START.md

场景 5: 我想用 VS Code 调试 Electron

打开 VS Code
按 F5 或点击"运行和调试"
选择 "Electron: Main Process"
开始调试 🐛

👉 详细配置查看 .vscode/launch.json

✅ 验证安装

运行这些命令确认一切正常：

# 1. 检查依赖安装
npm list electron

# 2. 编译 Electron 代码
npm run electron:build

# 3. 构建 Next.js（可选）
npm run build

# 4. 启动开发模式（需要开发依赖）
npm run app:dev

全部成功？恭喜！🎊

🚨 常见问题速查

Q: `npm run app:dev` 报错找不到命令？

A: 需要安装开发依赖：

npm install --save-dev electron-builder concurrently wait-on cross-env

Q: Electron 窗口启动后是空白的？

A: Next.js 服务器可能还在启动中，等待 10-20 秒。或者检查终端是否有错误。

Q: 如何关闭 Electron 只用浏览器开发？

A: 直接使用：

npm run dev

Q: 网络不好，依赖安装失败？

A: 使用国内镜像：

npm install --registry=https://registry.npmmirror.com

Q: 我需要添加应用图标吗？

开发阶段: 不需要，使用默认图标
打包发布: 需要，放在 build/ 目录

👉 更多问题查看 ELECTRON_QUICK_START.md 的"常见问题"部分

📦 项目结构一览

sensevox/
├── electron/              # Electron 主进程（新增）
│   ├── main.ts           # 应用入口
│   ├── preload.ts        # 安全 API 桥接
│   └── ...
├── src/
│   ├── app/              # Next.js 页面
│   ├── components/       # React 组件
│   │   └── electron-info.tsx  # Electron 信息组件（新增）
│   └── lib/
│       └── electron.ts   # Electron 工具库（新增）
├── build/                # 构建资源（新增）
│   └── entitlements.mac.plist
├── electron-builder.json5  # 打包配置（新增）
└── package.json          # 已更新脚本

🎓 学习路径

第 1 天：快速上手

✅ 阅读本文档（5 分钟）
✅ 阅读 ELECTRON_QUICK_START.md（10 分钟）
✅ 运行 npm run app:dev 启动应用

第 2 天：深入理解

✅ 阅读 README_ELECTRON.md（15 分钟）
✅ 查看 electron/main.ts 了解主进程
✅ 尝试修改窗口大小、标题等

第 3 天：实际开发

✅ 在组件中使用 isElectron() 检测环境
✅ 使用 getAppVersion() 获取版本信息
✅ 添加 Electron 特定功能

第 1 周：打包发布

✅ 添加应用图标
✅ 打包测试应用
✅ 配置代码签名（可选）

🛠️ npm 脚本速查

命令	说明	常用度
`npm run dev`	Next.js 开发服务器	⭐⭐⭐⭐⭐
`npm run app:dev`	Electron 开发模式	⭐⭐⭐⭐
`npm run electron:build`	编译 Electron 代码	⭐⭐⭐
`npm run build`	构建 Next.js	⭐⭐⭐
`npm run dist:mac`	打包 macOS 应用	⭐⭐
`npm run dist:win`	打包 Windows 应用	⭐⭐
`npm run dist:linux`	打包 Linux 应用	⭐⭐

🎨 功能特性

✅ 跨平台支持 - macOS、Windows、Linux
✅ 开发模式 - 热重载、开发者工具
✅ 生产就绪 - 应用签名、自动更新准备
✅ 安全设计 - Context Isolation、安全 IPC
✅ 完全兼容 - 不影响现有浏览器版本
✅ TypeScript - 完整的类型支持
✅ 文档齐全 - 5 篇详细文档

💡 提示

💰 节省时间

开发前端功能时，优先使用浏览器（npm run dev）
只在需要测试 Electron 特性时使用 npm run app:dev

🔒 安全第一

不要在渲染进程（React 组件）中使用 Node.js API
所有 Electron 功能通过 window.electron 访问

🚀 性能优化

Electron 应用首次启动较慢（启动 Next.js 服务器）
后续启动会更快

📱 应用图标

开发阶段可以不添加
正式发布前必须添加

📞 获取帮助

1. 查看文档

所有文档都在项目根目录，以 *.md 结尾。

2. 检查日志

主进程日志: 终端输出
渲染进程日志: 开发者工具 Console

3. 常见问题

ELECTRON_QUICK_START.md 包含大量常见问题解答。

4. 官方文档

🎯 下一步

现在你已经了解了基本情况，推荐的下一步：

👉 立即开始

npm install
npm run app:dev

👉 深入学习

阅读 ELECTRON_QUICK_START.md

👉 遇到问题

查看 INSTALLATION.md

🎉 结语

恭喜！你现在拥有了一个功能完整的 Next.js + Electron 桌面应用框架。

特性:

✅ 现代化的技术栈
✅ 完善的开发工具
✅ 详细的文档
✅ 生产级的配置

只需三步:

npm install - 安装依赖
npm run app:dev - 启动开发
开始编码！💻

准备好了吗？让我们开始吧！ 🚀

npm install && npm run app:dev

祝你开发愉快！ ✨

2025-10-30