Timeline 桌面客户端

记录生活中的每一个精彩时刻 - 桌面端应用

📖 项目简介

Timeline 桌面客户端是基于 Electron 构建的跨平台桌面应用，支持 Windows、macOS 和 Linux 系统。提供完整的离线支持、自动更新、系统托盘等功能。

🛠️ 技术栈

技术	版本	说明
Electron	28.x	跨平台桌面应用框架
Electron Vite	2.x	Electron 构建工具
TypeScript	5.x	类型安全
Electron Builder	24.x	打包与分发
Electron Updater	6.x	自动更新

📁 项目结构

timeline-desktop/
├── src/
│   ├── main/                    # 主进程代码
│   │   ├── main.ts              # 主进程入口
│   │   └── preload.ts           # Preload 脚本
│   └── renderer/                # 渲染进程（可选）
├── build/                       # 构建资源
│   ├── icon.ico                 # Windows 图标
│   ├── icon.icns                # macOS 图标
│   └── icon.png                 # Linux 图标
├── release/                     # 打包输出目录
├── package.json
├── electron.vite.config.ts      # Vite 配置
└── tsconfig.json

🚀 快速开始

环境要求

• Node.js >= 18.x
• npm >= 9.x 或 pnpm >= 8.x

安装依赖

# 使用 npm
npm install

# 或使用 pnpm
pnpm install

开发模式

# 启动开发服务器
npm run dev

开发模式下，应用会自动加载 http://localhost:8080（Web 前端开发服务器）。

构建打包

# 构建所有平台
npm run build
npm run dist

# 仅构建 Windows
npm run dist:win

# 仅构建 macOS
npm run dist:mac

# 仅构建 Linux
npm run dist:linux

📦 打包输出

打包完成后，安装包位于 release/ 目录：

release/
├── win-unpacked/               # Windows 免安装版
├── Timeline Setup 1.0.0.exe    # Windows 安装包
├── Timeline-1.0.0.dmg          # macOS 安装包
├── Timeline-1.0.0.AppImage     # Linux AppImage
└── timeline-desktop_1.0.0_amd64.deb  # Linux DEB 包

⚙️ 配置说明

应用配置 (package.json)

{
  "build": {
    "appId": "com.timeline.desktop",
    "productName": "Timeline",
    "directories": {
      "output": "release"
    },
    "win": {
      "icon": "build/icon.ico",
      "target": ["nsis"]
    },
    "mac": {
      "icon": "build/icon.icns",
      "target": ["dmg", "zip"]
    },
    "linux": {
      "icon": "build/icon.png",
      "target": ["AppImage", "deb"]
    }
  }
}

环境变量

变量名	说明	默认值
NODE_ENV	运行环境	development
API_URL	API 地址	https://api.timeline.com

🔄 自动更新

配置自动更新

1. 在 package.json 中配置发布地址：

{
  "build": {
    "publish": {
      "provider": "github",
      "owner": "your-github-username",
      "repo": "timeline-desktop"
    }
  }
}

2. 在 GitHub 创建 Release 并上传安装包

3. 应用启动时会自动检查更新

更新流程

应用启动 → 检查更新 → 发现新版本 → 提示用户 → 下载更新 → 安装更新

🔌 IPC 通信 API

渲染进程可用 API

// 获取应用版本
const version = await window.electronAPI.getVersion();

// 获取操作系统平台
const platform = await window.electronAPI.getPlatform();

// 检查更新
const updateInfo = await window.electronAPI.checkUpdate();

// 下载更新
await window.electronAPI.downloadUpdate();

// 安装更新
await window.electronAPI.installUpdate();

// 打开外部链接
await window.electronAPI.openExternal('https://timeline.com');

// 监听更新事件
window.electronAPI.onUpdateAvailable((info) => {
  console.log('发现新版本:', info.version);
});

window.electronAPI.onUpdateDownloaded((info) => {
  console.log('更新已下载:', info.version);
});

🖥️ 功能特性

系统托盘

• 最小化到托盘
• 托盘菜单快捷操作
• 点击托盘图标显示窗口

应用菜单

• 文件操作
• 编辑功能（撤销/重做/复制/粘贴）
• 视图控制（缩放/全屏）
• 帮助链接

安全特性

• Context Isolation 启用
• Node Integration 禁用
• 安全的 Preload 脚本

🔐 签名与公证

Windows 代码签名

# 设置环境变量
set CSC_LINK=path/to/certificate.pfx
set CSC_KEY_PASSWORD=your-password

# 打包时自动签名
npm run dist:win

macOS 公证

# 设置环境变量
set APPLE_ID=your-apple-id
set APPLE_ID_PASSWORD=app-specific-password
set APPLE_TEAM_ID=your-team-id

# 打包并公证
npm run dist:mac

📋 后续拓展计划

短期计划 (1-2 个月)

功能	描述	优先级
离线模式	支持离线浏览和编辑	P0
本地存储	数据本地缓存	P0
快捷键	全局快捷键支持	P1
多窗口	支持多窗口操作	P1
深色模式	跟随系统深色模式	P2

中期计划 (3-6 个月)

功能	描述	优先级
批量导入	批量导入本地照片/视频	P1
本地备份	数据本地备份与恢复	P1
剪贴板监听	自动识别剪贴板图片	P2
文件拖放	拖放文件快速上传	P2
系统通知	原生系统通知	P2

长期计划 (6-12 个月)

功能	描述	优先级
插件系统	支持第三方插件	P2
主题定制	自定义主题和样式	P3
多语言	国际化支持	P3
云同步	数据云同步	P3

🐛 常见问题

Q: 开发模式下白屏？

检查 Web 前端开发服务器是否启动：

cd ../timeline-frontend
pnpm dev

Q: 打包后应用无法启动？

检查 main.ts 中的资源路径是否正确：

// 生产环境应使用打包后的路径
mainWindow.loadFile(path.join(__dirname, '../renderer/index.html'));

Q: 自动更新不生效？

1. 检查 publish 配置是否正确
2. 确保 GitHub Release 已发布
3. 检查网络连接

📞 技术支持

• 问题反馈: https://github.com/timeline/timeline-desktop/issues
• 文档地址: https://docs.timeline.com/desktop

📄 许可证

MIT License