GameResX 是为游戏开发团队设计的美术资源管理工具，主要用于游戏换皮场景。支持：
- 可视化管理和分类美术资源（UI、Icon、贴图等）
- AI 生成图与原始图的对比预览
- 批量管理资源标签和生图提示词（规划中）
- 自动化资源替换流程（规划中）
第一阶段（已完成）：轻量版文件管理器，聚焦图片资源的树状浏览和双区域可视化预览。
-
📁 目录浏览
- 树状目录结构，仿 Mac Finder 分栏模式
- 自动过滤和识别包含图片的文件夹
- 支持展开/折叠，实时导航
-
🖼️ 图片预览
- 中间栏：小图对比（原图 + 占位图并排显示）
- 右侧栏：大图详细对比，左右分屏
- 支持图片格式：PNG、JPG、JPEG、WebP
-
🔍 交互功能
- 图片懒加载优化性能
- 鼠标滚轮缩放（0.1x - 10x）
- 鼠标拖拽平移
- 一键重置视图
-
🎨 界面设计
- 深色主题，护眼友好
- 三栏自适应布局
- 流畅的动画过渡
- macOS 原生窗口样式
-
资源管理
- 资源标签系统
- AI 生图提示词管理
- 原始资源缓存机制
- 批量操作支持
-
AI 集成
- AI 生图 API 对接
- 自动化资源替换
- 提示词模板库
-
高级对比
- 图片元数据展示（尺寸、格式、大小）
- 像素级对比
- 色差分析
- 同步缩放模式
-
增强功能
- 文件重命名/移动
- 批量导入/导出
- 快捷键定制
- 主题切换
- Node.js: >= 18.0.0（推荐 20+）
- npm: >= 9.0.0
- 操作系统: macOS 10.13+ / Windows 10+
# 克隆项目
git clone <repository-url>
cd GameResX
# 安装依赖
npm install# 启动开发服务器（热重载）
npm run dev# 构建生产版本
npm run build
# 打包 macOS 应用
npm run build:mac
# 打包 Windows 应用
npm run build:win- 启动应用后，点击"选择目录"按钮
- 选择游戏项目的美术资源根目录
- 左侧树状目录会显示所有包含图片的文件夹
- 点击文件夹，中间栏显示该文件夹下的图片列表
- 点击图片，右侧栏显示大图对比（目前生成图为占位图）
- 使用鼠标滚轮缩放，拖拽平移查看细节
| 层级 | 技术 | 说明 |
|---|---|---|
| 桌面框架 | Electron 28 | 跨平台桌面应用 |
| 构建工具 | Vite + electron-vite | 快速构建，HMR 支持 |
| 前端框架 | React 18 | 组件化 UI |
| 开发语言 | TypeScript 5 | 类型安全 |
| 样式方案 | Tailwind CSS | 实用优先的 CSS 框架 |
| 状态管理 | Zustand | 轻量级状态管理 |
| 图标库 | Lucide React | 现代化图标 |
GameResX/
├── src/
│ ├── main/ # Electron 主进程
│ │ ├── index.ts # 主进程入口，窗口管理
│ │ └── fileSystem.ts # 文件系统操作（扫描、读取）
│ │
│ ├── preload/ # 预加载脚本
│ │ └── index.ts # 暴露安全 API 给渲染进程
│ │
│ └── renderer/ # 渲染进程（React 应用）
│ ├── index.html # HTML 入口
│ └── src/
│ ├── main.tsx # React 入口
│ ├── App.tsx # 根组件
│ │
│ ├── components/ # UI 组件
│ │ ├── layout/
│ │ │ └── ThreeColumnLayout.tsx # 三栏布局
│ │ ├── sidebar/
│ │ │ ├── FolderTree.tsx # 目录树
│ │ │ └── TreeNode.tsx # 树节点
│ │ ├── filelist/
│ │ │ ├── FileList.tsx # 文件列表
│ │ │ └── FileItem.tsx # 文件项（小图对比）
│ │ └── preview/
│ │ └── CompareView.tsx # 大图对比
│ │
│ ├── stores/ # 状态管理
│ │ └── useAppStore.ts # 全局状态
│ │
│ ├── hooks/ # 自定义 Hooks
│ │ ├── useFileSystem.ts # 文件系统操作
│ │ └── useLazyImage.ts # 图片懒加载
│ │
│ ├── types/ # TypeScript 类型
│ │ └── index.ts
│ │
│ └── styles/
│ └── index.css # 全局样式
│
├── resources/ # 应用资源
├── out/ # 构建输出（自动生成）
│
├── electron.vite.config.ts # electron-vite 配置
├── package.json
├── tsconfig.json
├── tsconfig.node.json # Node 环境配置（主进程/预加载）
├── tsconfig.web.json # Web 环境配置（渲染进程）
├── tailwind.config.js
└── postcss.config.js
┌─────────────────────────────────────────────────────────────┐
│ Electron 应用 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ IPC ┌──────────────┐ │
│ │ 渲染进程 │◄──────────────────►│ 主进程 │ │
│ │ (React UI) │ contextBridge │ (Node.js) │ │
│ │ │ │ │ │
│ │ • App.tsx │ │ • 窗口管理 │ │
│ │ • Components │ │ • 文件扫描 │ │
│ │ • Zustand Store │ │ • 图片读取 │ │
│ └─────────────────┘ └──────────────┘ │
│ ▲ │ │
│ │ │ │
│ └────────── Preload Script ──────────────┘ │
│ • 安全 API 暴露 │
│ • 类型定义 │
└─────────────────────────────────────────────────────────────┘
用户操作 → UI 组件 → Zustand Action → IPC 调用 → 主进程处理 → 返回数据 → 更新 Store → 重新渲染
职责：
- 创建和管理应用窗口
- 处理文件系统操作（Node.js API）
- 响应渲染进程的 IPC 请求
核心功能：
// src/main/fileSystem.ts
- scanDirectory(rootPath): 扫描目录，构建树状结构
- getImagesInFolder(folderPath): 获取文件夹中的图片列表
- readImageAsBase64(imagePath): 读取图片为 base64安全考虑：
- 仅主进程可访问文件系统
- 所有文件操作需通过 IPC 验证
- 使用
contextIsolation: true
职责：
- 通过
contextBridge暴露安全 API - 作为主进程和渲染进程的桥梁
API 定义：
window.api = {
selectDirectory(): Promise<string | null>
scanDirectory(rootPath: string): Promise<TreeNode[]>
getImagesInFolder(folderPath: string): Promise<ImageFile[]>
readImageAsBase64(imagePath: string): Promise<string>
}职责：
- 渲染 UI 界面
- 处理用户交互
- 管理应用状态
状态管理（Zustand）：
interface AppState {
rootPath: string | null // 根目录路径
directoryTree: TreeNode[] // 目录树
selectedFolderPath: string | null // 选中的文件夹
imageList: ImageFile[] // 图片列表
selectedImage: ImageFile | null // 选中的图片
expandedFolders: Set<string> // 展开的文件夹
isLoading: boolean // 加载状态
}组件层次：
App.tsx
├── ThreeColumnLayout.tsx
│ ├── FolderTree.tsx
│ │ └── TreeNode.tsx (递归)
│ ├── FileList.tsx
│ │ └── FileItem.tsx (懒加载)
│ └── CompareView.tsx (缩放/平移)
-
图片懒加载
- 使用
IntersectionObserver监听可视区域 - 仅加载用户可见的图片
- 避免一次性加载大量图片导致卡顿
- 使用
-
虚拟滚动（可扩展）
- 当前使用原生滚动
- 后续可集成
react-window处理超大列表
-
Base64 缓存（规划）
- 主进程可添加图片缓存层
- 减少重复读取文件
// src/main/fileSystem.ts
export async function newFeature(params: any): Promise<any> {
// 实现逻辑
}
// src/main/index.ts
ipcMain.handle('namespace:action', async (_, params) => {
return await newFeature(params)
})// src/preload/index.ts
const api = {
// ...existing
newFeature: (params: any): Promise<any> => {
return ipcRenderer.invoke('namespace:action', params)
}
}// src/renderer/src/hooks/useNewFeature.ts
export function useNewFeature() {
const handleAction = async () => {
const result = await window.api.newFeature(params)
// 处理结果
}
return { handleAction }
}// src/renderer/src/components/NewFeature.tsx
export function NewFeature() {
const { handleAction } = useNewFeature()
// 渲染 UI
}- TypeScript 严格模式：所有代码必须通过类型检查
- 组件命名：PascalCase（如
FileList.tsx） - Hooks 命名：use 前缀（如
useFileSystem.ts） - 样式：优先使用 Tailwind 实用类
- 状态管理：通过 Zustand store 集中管理
# 开启 Electron DevTools
在 App 中按 Cmd+Option+I (Mac) 或 Ctrl+Shift+I (Windows)
# 查看主进程日志
查看终端输出
# 查看渲染进程日志
打开 DevTools ConsoleQ: 图片不显示？
- 检查文件路径是否正确
- 确认图片格式是否支持（png/jpg/jpeg/webp）
- 查看 DevTools Console 是否有错误
Q: 目录树为空？
- 确认选择的目录下有图片文件
- 检查文件夹权限
Q: 性能卡顿？
- 检查图片数量，超大列表需要虚拟滚动
- 优化图片大小，考虑生成缩略图
- 项目初始化和架构搭建
- 三栏布局界面
- 目录树浏览
- 图片列表展示
- 大图对比预览
- 基础交互（缩放/平移）
- 缓存目录配置
- 生成图管理逻辑
- 图片元数据展示
- 资源标签系统
- 提示词输入和编辑
- AI 生图 API 集成
- 批量生成和替换
- 高级对比功能
- 导入/导出功能
- 插件系统
{
"@electron-toolkit/utils": "^4.0.0", // Electron 工具集
"lucide-react": "^0.424.0", // 图标库
"zustand": "^4.5.4" // 状态管理
}{
"electron": "^28.3.3", // Electron 框架
"electron-vite": "^2.3.0", // 构建工具
"react": "^18.3.1", // UI 框架
"typescript": "^5.5.4", // TypeScript
"tailwindcss": "^3.4.7", // CSS 框架
"vite": "^5.4.2" // 构建工具
}使用语义化提交信息：
feat: 添加新功能
fix: 修复 bug
docs: 文档更新
style: 代码格式调整
refactor: 重构代码
perf: 性能优化
test: 测试相关
chore: 构建/工具配置
main: 稳定版本develop: 开发分支feature/*: 新功能分支fix/*: Bug 修复分支
本项目仅供学习和内部使用。
如有问题或建议，请提交 Issue。
构建工具: Electron + React + TypeScript
最后更新: 2026-01-24
当前版本: v1.0.0