# folder-diff

**Repository Path**: hubu8/folder-diff

## Basic Information

- **Project Name**: folder-diff
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-26
- **Last Updated**: 2026-07-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 文件夹对比工具

一个基于 Electron 的文件夹对比工具，采用安全的进程隔离架构，支持哈希级精确对比、行级差异高亮和文件内容覆盖功能。

## 功能特点

- 文件夹对比：递归扫描并对比两个文件夹中的文件差异
- 哈希级精确对比：对大小相同的文件使用 SHA256 哈希二次校验，避免“大小相同但内容不同”的误判
- 行级差异对比：使用 `diff` 库进行行级差异显示（当前为行级高亮，后续可扩展为字符级 inline 高亮）
- 差异高亮：绿色表示新增、红色表示删除、白色表示未修改
- 内容覆盖：支持将差异行从一个文件复制到另一个文件，覆盖前自动备份原文件
- 二进制检测：自动识别二进制文件，避免误读损坏数据
- 忽略规则：支持按目录名和文件名通配符（如 `*.log`）跳过不需要对比的内容
- 搜索过滤：左侧文件树支持按文件名实时过滤
- 进度提示：大目录扫描和哈希校验时显示实时进度
- 界面优化：左侧边栏可拖拽调整宽度，双栏对比区域也可调整比例
- 安全架构：使用 `preload.js` + `contextBridge` + `contextIsolation`，所有文件读写均校验路径范围

## 安装和运行

### 安装依赖

```bash
npm install
```

### 启动应用

```bash
npm start
```

## 打包为可执行文件（.exe）

### 安装打包工具

如果还未安装 `electron-builder`，需先执行：

```bash
npm install --save-dev electron-builder
```

### 打包命令

打包当前平台的安装包：

```bash
npm run build
```

指定打包目标平台：

```bash
# Windows（生成 .exe 安装包 + 便携版）
npm run build:win

# macOS（生成 .dmg）
npm run build:mac

# Linux（生成 .AppImage）
npm run build:linux
```

### 打包产物

打包完成后，产物输出到 `dist/` 目录：

| 文件 | 说明 |
|------|------|
| `Folder Diff Setup x.x.x.exe` | NSIS 安装程序，双击即可安装 |
| `Folder Diff x.x.x.exe` | 便携版，无需安装，双击直接运行 |
| `Folder Diff-x.x.x.dmg` | macOS 安装包 |
| `Folder Diff-x.x.x.AppImage` | Linux 免安装版 |

### 图标配置

如果需要自定义应用图标，将图标文件放到项目根目录：

- Windows: `icon.ico`（建议 256×256）
- macOS: `icon.icns`（建议 512×512）
- Linux: `icon.png`（建议 512×512）

如果图标文件不存在，打包时将使用 Electron 默认图标。

---

## 使用说明

1. **选择文件夹**
   - 点击“文件夹1”的“浏览”按钮，选择第一个要对比的文件夹
   - 点击“文件夹2”的“浏览”按钮，选择第二个要对比的文件夹

2. **设置忽略规则（可选）**
   - 点击“设置”按钮，输入要忽略的目录名或文件名，每行一个
   - 支持通配符，例如 `node_modules`、`.git`、`*.log`

3. **开始对比**
   - 点击“开始对比”按钮，工具会异步扫描并对比两个文件夹
   - 左侧会显示文件树，顶部状态栏显示“相同 / 差异 / 仅左 / 仅右”数量

4. **查看差异**
   - 点击左侧文件树中的文件，右侧会显示该文件的详细差异
   - 黄色背景表示文件有差异
   - 蓝色背景表示仅存在于文件夹1
   - 红色背景表示仅存在于文件夹2

5. **差异显示**
   - 绿色背景：添加的内容
   - 红色背景：删除的内容（带删除线）
   - 白色背景：未修改的内容

6. **内容覆盖**
   - 鼠标悬停在差异行上，会显示“复制到左边”或“复制到右边”按钮
   - 点击按钮前会弹出确认对话框，确认后会自动备份目标文件并写入新内容

## 技术栈

- Electron：桌面应用框架
- Node.js：文件系统操作
- `diff`：行级差异对比算法
- HTML/CSS/JavaScript：用户界面

## 安全说明

- 渲染进程不再开启 `nodeIntegration`，通过 `preload.js` 的 `contextBridge` 暴露最小必要接口
- 所有文件读写路径都会被校验，确保只能访问用户选择的两个对比文件夹内的文件
- HTML 中设置了 Content-Security-Policy，减少 XSS 风险

## 注意事项

- 请确保选择的文件夹路径正确
- 大文件对比可能需要一些时间，工具会显示进度条
- 覆盖操作会自动备份原文件到 Electron 用户数据目录下的 `folder-compare-backups` 文件夹中
- 二进制文件目前仅提示“不支持文本对比”，不会被误读为文本

## 开发

项目结构：

```
folder-diff/
├── main.js              # Electron 主进程，负责 IPC、窗口管理、文件监控
├── preload.js           # contextBridge 安全桥接，暴露最小必要 API
├── index.html           # 应用入口页面（CSS 外链）
├── package.json         # 项目配置与 electron-builder 打包配置
├── src/
│   ├── scanner.js       # 异步递归文件扫描
│   ├── diff-engine.js   # SHA256 哈希对比 + 行级差异计算
│   ├── utils.js         # 路径校验、哈希、二进制检测等工具函数
│   └── file-watcher.js  # 文件变更监控（fs.watch）
├── renderer/
│   ├── app.js           # 渲染进程入口，初始化所有模块
│   ├── state.js         # 发布/订阅状态管理
│   ├── file-tree.js     # 左侧文件树渲染与事件
│   ├── diff-view.js     # 行级差异渲染、折叠未修改区域
│   ├── virtual-scroll.js # 虚拟滚动引擎（>1000行自动启用）
│   ├── tabs.js          # 多标签页管理
│   ├── search-bar.js    # 差异内容搜索
│   ├── settings.js      # 设置持久化（localStorage）
│   ├── copy-ops.js      # 差异行/块覆盖操作
│   ├── export.js        # 导出对比报告
│   └── components/
│       ├── context-menu.js   # 右键上下文菜单
│       ├── toast.js          # Toast 通知
│       └── confirm-dialog.js # 自定义确认对话框
└── styles/
    ├── layout.css
    ├── sidebar.css
    ├── file-tree.css
    ├── diff-panel.css
    ├── context-menu.css
    └── components.css
```