Wallhaven 壁纸浏览器
项目地址： https://github.com/xiaobili/wallhaven
一款优雅的跨平台桌面壁纸浏览与下载应用
基于 Electron + Vue 3 + TypeScript 构建
版本亮点 • 功能特性 • 技术栈 • 快速开始 • 项目结构
该项目参考了 leoFitz1024 的 Wallhaven 项目，并进行了大量优化和扩展。RESPECT
本项目使用 AI 辅助开发工具实现。
✨ 版本亮点 (v2.3.0)
本项目已完成全面架构重构，在保持用户体验不变的前提下，实现了代码架构的大幅升级：
- 🏗️ 分层架构: Client → Repository → Service → Composable → View 清晰分层
- 🔌 IPC 模块化: 866 行单文件拆分为 8 个独立 handler ，职责清晰
- 🛡️ 类型安全: 消除 60+ 处
any类型，100% TypeScript 覆盖 - ⚠️ 错误处理: 全局错误处理器 + 组件级 ErrorBoundary 双重保障
- 📦 代码复用: useAlert 等 composables 消除 76 行重复代码
- 🧹 代码清理: 移除 5 个测试/演示文件，路由懒加载优化
- ⭐ 收藏功能: 完整的收藏夹管理系统，O(1) 高效查询
- ⬇️ 断点续传: 下载支持暂停/恢复，重启后自动恢复任务
🎯 项目简介
Wallhaven 是一个功能丰富的跨平台桌面壁纸浏览和管理应用，提供：
- 🔍 强大的搜索功能（关键词、分类、纯度、分辨率等）
- 🖼️ 流畅的图片预览和下载
- 💾 批量下载管理（支持暂停/恢复、断点续传）
- ⭐ 收藏夹管理（创建、重命名、删除、多收藏夹支持）
- 💻 桌面壁纸设置（ 6 种适配模式）
- 📁 本地壁纸管理
- 🌐 跨平台支持（ macOS 、Windows 、Linux ）
- ⚡ 无限滚动加载，浏览体验流畅
🚀 核心功能
1. 在线壁纸搜索
支持多种筛选条件：
- 关键词搜索
- 分类筛选（普通、动漫、人物）
- 纯度筛选（ SFW 、Sketchy 、NSFW ）
- 分辨率选择
- 比例筛选
- 颜色筛选
- 排序方式（相关性、随机、日期、浏览量等）
2. 本地壁纸管理
- 浏览已下载的壁纸
- 设置为桌面壁纸
- 删除本地文件
3. 图片预览
- 大图预览
- 全屏查看
- 流畅的动画效果
- 键盘快捷键支持（上一张/下一张）
4. 下载管理
- 批量下载
- 多线程支持（ 1-10 ）
- 暂停/恢复功能
- 进度追踪
- 断点续传：网络中断后自动恢复
- 持久化：重启应用后自动恢复未完成任务
5. 收藏夹
- 创建自定义收藏夹
- 重命名、删除收藏夹
- 快捷收藏：左键快速收藏到默认收藏夹
- 收藏选择器：右键选择目标收藏夹
- 多收藏夹支持：单个壁纸可属于多个收藏夹
- O(1) 高效查询：大数据量下依然流畅
6. 应用设置
提供丰富的个性化配置选项：
-
下载设置
- 自定义下载目录
- 多线程下载数量调节（ 1-10 ）
-
API 设置
- Wallhaven API Key 配置
- 支持 NSFW 内容访问
-
桌面设置
- 6 种壁纸适配模式（填充、适应、拉伸、平铺、居中、跨屏）
- 实时预览效果
-
缓存管理
- 查看缓存占用
- 一键清理缩略图和临时文件
🛠️ 技术栈
| 类别 | 技术 | 版本 |
|---|---|---|
| 桌面框架 | Electron | v41.2.2 |
| 前端框架 | Vue 3 (Composition API) | v3.5.32 |
| 构建工具 | electron-vite / Vite | v5.0.0 / v7.3.2 |
| 语言 | TypeScript | v6.0.0 |
| 状态管理 | Pinia | v3.0.4 |
| 路由 | Vue Router | v5.0.4 |
| HTTP 客户端 | Axios | v1.15.0 |
| 图片处理 | Sharp | v0.34.5 |
| 打包工具 | electron-builder | v26.8.1 |
🚀 快速开始
环境要求
- Node.js
^20.19.0或>=22.12.0 - npm 或 yarn 或 pnpm
安装依赖
npm install
开发模式
# 启动 Electron 桌面应用（支持热重载）
npm run dev
# 仅在浏览器中预览
npm run preview
构建应用
# Windows
npm run build:win
# macOS
npm run build:mac
# Linux
npm run build:linux
构建产物将输出到 release/ 目录。
其他命令
# 类型检查
npm run type-check
# 代码检查
npm run lint
# 代码格式化
npm run format
# 单元测试
npm run test:unit
📁 项目结构
wallhaven/
├── electron/ # Electron 主进程代码
│ ├── main/ # 主进程
│ │ ├── index.ts # 应用入口、窗口管理
│ │ └── ipc/ # IPC 处理器模块（ 8 个独立 handler ）
│ │ ├── base.ts # 基础类型和工具函数
│ │ ├── file.handler.ts # 文件操作
│ │ ├── download.handler.ts # 下载管理
│ │ ├── settings.handler.ts # 设置存储
│ │ ├── wallpaper.handler.ts # 壁纸设置
│ │ ├── window.handler.ts # 窗口控制
│ │ ├── cache.handler.ts # 缓存管理
│ │ └── api.handler.ts # API 代理
│ └── preload/ # 预加载脚本
│ └── index.ts # 暴露安全 API 给渲染进程
│
├── src/ # Vue 渲染进程代码
│ ├── clients/ # 客户端层 (Electron API 封装)
│ │ ├── ElectronClient.ts # Electron API 封装
│ │ └── ApiClient.ts # HTTP 请求封装
│ ├── composables/ # 组合式函数层
│ │ ├── core/ # 核心功能 (useAlert 等)
│ │ ├── download/ # 下载相关
│ │ ├── favorites/ # 收藏相关
│ │ ├── local/ # 本地壁纸相关
│ │ ├── settings/ # 设置相关
│ │ └── wallpaper/ # 壁纸相关
│ ├── components/ # Vue 组件
│ ├── errors/ # 自定义错误类
│ ├── repositories/ # 数据仓库层
│ ├── router/ # 路由配置
│ ├── services/ # 服务层
│ ├── stores/ # Pinia 状态管理
│ ├── types/ # TypeScript 类型定义
│ ├── utils/ # 工具函数
│ └── views/ # 页面组件
│ ├── OnlineWallpaper.vue # 在线壁纸页
│ ├── LocalWallpaper.vue # 本地壁纸页
│ ├── DownloadWallpaper.vue # 下载中心页
│ ├── FavoritesPage.vue # 收藏页
│ └── SettingPage.vue # 设置页
│
├── resources/ # 应用资源（图标等）
├── scripts/ # 构建脚本
└── .planning/ # 项目规划文档
🏗️ 架构设计
分层架构
项目采用清晰的分层架构，确保代码的可维护性和可测试性：
┌─────────────────────────────────────────────────────────┐
│ View Layer │
│ (OnlineWallpaper, LocalWallpaper, DownloadWallpaper, │
│ FavoritesPage, SettingPage) │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ Composable Layer │
│ (useAlert, useWallpaperList, useDownload, useSettings,│
│ useFavorites, useCollections) │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ Service Layer │
│ (WallpaperService, DownloadService, SettingsService, │
│ FavoritesService, CollectionsService) │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ Repository Layer │
│ (WallpaperRepository, DownloadRepository, │
│ SettingsRepository, FavoritesRepository) │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ Client Layer │
│ (ElectronClient, ApiClient) │
└─────────────────────────────────────────────────────────┘
分层约束
- Views 不直接访问 Store ，必须通过 Composables
- Views 不直接调用 electronAPI ，必须通过 Services
- Composables 封装业务逻辑，协调 Service 和 Store
进程模型
- 主进程：应用生命周期管理、原生 API 调用、文件系统操作
- 渲染进程：Vue 应用，负责 UI 渲染和用户交互
- 预加载脚本：安全桥接主进程和渲染进程的通信
📝 版本历史
| 版本 | 发布日期 | 主要功能 |
|---|---|---|
| v2.6 | 2026-04-29 | 设置页缓存优化 |
| v2.5 | 2026-04-29 | 壁纸收藏功能 |
| v2.4 | 2026-04-27 | ImagePreview 导航功能 |
| v2.3 | 2026-04-27 | ElectronAPI 分层重构 |
| v2.2 | 2026-04-27 | Store 分层迁移 |
| v2.1 | 2026-04-27 | 下载断点续传 |
| v2.0 | 2026-04-26 | 架构重构 |
🤝 贡献指南
欢迎提交 Issue 和 Pull Request ！
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 开启 Pull Request
📄 许可证
本项目采用 MIT 许可证 - 详见 LICENSE 文件
🙏 致谢
- leoFitz1024/wallhaven - 项目灵感来源
- Wallhaven - 提供优质的壁纸 API
- Vue.js - 渐进式 JavaScript 框架
- Electron - 跨平台桌面应用框架
- Vite - 下一代前端构建工具
- Pinia - Vue 状态管理
Made with ❤️ by BillyJR