# 哪个文件夹在变大

**Repository Path**: az13js/who-grew

## Basic Information

- **Project Name**: 哪个文件夹在变大
- **Description**: 用来找出"哪个目录在偷偷变大"的工具集：扫描目录生成容量快照、对比两次快照的差异、在浏览器里可视化目录大小分布，帮你快速定位容量增长的元凶。
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-12
- **Last Updated**: 2026-09-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WhoGrew · 谁在变大

用来找出"哪个目录在偷偷变大"的工具集：扫描目录生成容量快照、对比两次快照的差异、在浏览器里可视化目录大小分布，帮你快速定位容量增长的元凶。

项目由两部分组成：

- **根目录的 PHP CLI 脚本**：负责在系统上实际扫描目录、生成/比较 CSV、批量清空目录。
- **`file_analyzer/` 的 Web 前端**：把 CSV 上传到浏览器，用树形 / 方块树（Treemap）可视化目录大小，并支持两次扫描的差异对比。

两部分共用同一种 CSV 格式，改动时必须同步。

---

## 目录结构

```
scan_files/
├── scan_files.php          # 扫描目录，输出 CSV
├── compare.php             # 比较两份 CSV，按目录深度汇总差异
├── safe_delete.php         # 按 safe_delete_dirs.txt 清单清空目录（破坏性）
├── safe_delete_dirs.txt    # 待清空目录清单（已被 .gitignore 忽略）
├── file_sizes_report_*.csv # 扫描输出（已被 .gitignore 忽略）
└── file_analyzer/          # 前端 Web App（Vite + vitest，纯原生 JS）
    ├── index.html
    ├── package.json
    ├── vite.config.js
    ├── src/
    │   ├── core/           # 纯逻辑，全部有单测：csvParser / pathUtils /
    │   │                   # aggregator / comparator / treeBuilder /
    │   │                   # treemap / formatter
    │   ├── ui/             # DOM 视图：app / analyzerView / compareView /
    │   │                   # treemapRenderer / main
    │   └── styles/main.css
    └── tests/              # 与 src/core 一一对应的 vitest 测试
```

---

## 前置依赖

- **PHP 7.4+**
- **Node.js + npm**（`file_analyzer/`）
- `file_analyzer/.npmrc` 已将 npm registry 指向 `registry.npmmirror.com`（国内镜像），首次运行需要执行 `npm install` 拉取依赖。

---

## 快速开始

### 1. 扫描目录并生成 CSV

```bash
php scan_files.php <目录路径>
```

- 输出到当前工作目录下的 `file_sizes_report_YYYYMMDD.csv`（按当天日期命名）。
- 递归遍历，遇无权限目录会打印警告并跳过；符号链接一律跳过，避免循环或越权。

### 2. 比较两份 CSV

```bash
php compare.php [-d 深度] file1.csv file2.csv
```

- `-d` 指定目录深度，默认 `2`。
- 以 `file1.csv` 为基线，输出 `file2.csv` 相对它的每个目录的字节增减，按增量从大到小排列。
- 示例输出：

```
C:\A\A_SUB1 + 80 B
C:\A\A_SUB2 - 1.5 KB
```

### 3. 在浏览器中可视化

```bash
cd file_analyzer
npm install
npm run dev
```

浏览器打开 Vite 打印的地址，可以：

- **单文件分析**：上传一份 `file_sizes_report_*.csv`，查看总大小、文件数、Top 文件、按扩展名统计、目录树与方块树可视化。
- **文件对比**：上传两份 CSV，对比每次扫描之间的目录级与文件级变化。

生产构建：

```bash
npm run build       # 产物输出到 file_analyzer/dist
npm run preview     # 本地预览构建产物
```

---

## CSV 格式约定（PHP 与 JS 共用）

```csv
"File Path","Size (bytes)"
"C:\\A\\A_SUB1\\a.txt",86
"C:\\A\\A_SUB2\\b.docx",106
```

- 表头必须严格为 `"File Path","Size (bytes)"`，JS 端 `validateCSV` 缺失即失败。
- 每行一个文件；`Size` 为非负整数（字节）。
- 路径统一使用 Windows 反斜杠；CSV 字段内的 `\\` 转义需先解转义（JS `unescapePath`、PHP `str_replace`）。
- 路径规范化会把 `\\`、`/` 折叠成单个 `\`（`pathUtils.normalizePath`）。
- 深度切片时，Windows 盘符 `C:\` 算作一段，所以深度 `N` 在 Windows 上取 `N+1` 段、在 Linux 上取 `N` 段。这条规则同时实现于 `pathUtils.getDirectory`、`aggregator.getDirectoryAtDepth`、`compare.php` 的 `extractDirectoryAtDepth`，改动时必须三处同步。

---

## 安全删除（慎用）

`safe_delete.php` 会读取当前目录下的 `safe_delete_dirs.txt`（每行一个目录路径，请根据自己电脑的情况自行决定和配置要清空的目录），把每个目录的内容清空但保留目录本身。

```bash
php safe_delete.php
```

- **破坏性操作**，请先备份或确认清单。
- `safe_delete_dirs.txt` 已被 `.gitignore` 忽略。
- 删除失败的目录/文件会逐条打印到 stdout。

---

## 测试

```bash
cd file_analyzer
npm install
npm test             # vitest run，跑全部用例
npm run test:watch   # 监听模式
npx vitest run tests/aggregator.test.js   # 单个测试文件
npx vitest -t "用例名"                    # 按用例名筛选
```

- 测试环境为 `node`（`vite.config.js` → `test.environment`）。
- `globals: true` 已开启，但现有用例仍显式 `import { describe, it, expect } from 'vitest'`，新增用例请保持显式导入。
- `src/core/` 每个文件都有对应测试；`src/ui/` 目前无测试。修改 `src/core/*` 时请同步更新测试。

---

## 语言与风格约定

- 界面文案为简体中文（zh-CN），以字符串字面量硬编码在 `src/ui/*.js` 中，**没有 i18n 层**。新增文案请保持中文，不要引入英文 UI 字符串。
- PHP 与 JS 的注释、文档串多为中文，新代码请延续这一风格。

---

## Git 忽略项

`.gitignore` 已忽略：

- 根目录 `*.csv`、`safe_delete_dirs.txt`
- `file_analyzer/dist`、`file_analyzer/node_modules`

不要提交这些文件。