FolderVisualizer

v0.2.0 · 面向 Windows 的本地文件夹结构可视化工具

FolderVisualizer 将真实文件夹结构转换为比 cmd/tree 更直观的横向可视化地图。选择一个文件夹后，程序会自动判断目录规模：中小目录展示完整文件树，超大目录使用逐层分页浏览，避免浏览器一次加载全部节点。

扫描、索引和浏览都在本机完成，不会上传文件、路径或扫描数据。

示例

Small：完整横向文件树

Large：逐层按需浏览

Large：当前路径 SVG 导出

下载与使用

普通 Windows 用户

v0.2.0 Release 发布后，请从项目的 GitHub Releases 页面下载：

FolderVisualizer-v0.2.0-windows-x64.zip

1. 完整解压 ZIP。
2. 保留 FolderVisualizer.exe、_internal 和其他文件的相对位置。
3. 双击 FolderVisualizer.exe。
4. 选择文件夹并点击“开始分析”。

这是 PyInstaller onedir 便携包，不是单文件 EXE，也不是安装程序。不要只复制或移动 FolderVisualizer.exe。Windows ZIP 用户不需要安装 Python。

Python 用户

项目运行不依赖第三方 Python 包；当前开发和测试环境为 Python 3.11。

启动 GUI：

python gui.py

使用命令行统一入口：

python launcher.py "D:\目标目录"

不提供 CLI EXE；命令行入口仅用于源码运行。

为什么使用 FolderVisualizer

• 真实层级更清楚：根目录位于左侧，子目录和文件按照深度向右展开。
• 大小目录自动适配：程序自动选择完整文件树或大型文件夹浏览方式。
• 超大目录按需加载：每次只读取当前目录的直接子节点，每页最多 300 个节点。
• 查找和查看更方便：完整树支持名称搜索、定位、缩放和文件名展开。
• 结果可以导出：支持 small 完整树 SVG，以及 large 当前浏览路径与当前页快照 SVG。
• 完全本地运行：不需要云服务，不上传扫描数据。

两种浏览模式

功能	small：完整文件树	large：大型文件夹浏览
展示方式	一次展示全部文件和目录	从根目录开始逐层按需读取
适用范围	中小目录	节点很多或单层内容很多的目录
搜索	支持文件名和目录名搜索	暂不支持全局搜索
浏览操作	横纵滚动、缩放、定位	点击目录向右增加一列
分页	不需要	每页最多 300 个直接子节点
SVG	完整文件树	当前路径、分页信息和当前页节点

程序会根据节点数量、最大直接子节点数量和扫描结果大小自动选择模式。源码 CLI 还可以使用 --force-large 强制进入 large 模式；不提供 --force-small。

功能概览

small 完整文件树

• 完整保留文件和目录节点。
• 使用横向分层布局和 SVG 直角连接线。
• 根据扩展名显示常见文件类型图标。
• 显示文件数、目录数、总大小和主要文件类型统计。
• 支持名称搜索、匹配高亮、上一个/下一个和自动定位。
• 支持缩小、放大、恢复 100%、适应窗口和 Ctrl + 鼠标滚轮缩放。
• 长文件名优先保留扩展名；悬停显示完整名称和路径。
• 点击文件节点可以展开或恢复完整文件名。
• 页面工具栏可以导出独立 SVG。

large 大型文件夹浏览

• 从根目录开始，由左向右逐层查看。
• 点击同一层的其他目录时，替换右侧已打开的列。
• 每页最多读取和显示 300 个直接子节点。
• 提供上一页、下一页、当前范围和总页数。
• 保留文件类型图标和完整路径提示。
• 可以导出“当前路径 + 当前页”的 SVG 浏览快照。

GUI 与 CLI

• Tkinter GUI 在后台线程执行扫描，窗口不会因扫描任务占用主线程。
• 扫描完成后自动打开系统默认浏览器。
• large 模式由 GUI 启动动态端口的本地浏览服务。
• 关闭 GUI 时会停止 large 本地服务。
• launcher.py保留 --force-large、--port和 --no-open参数。

源码中还保留基础 HTML 报告和大目录一级概览 SVG 等独立工具；它们不是 GUI 标准流程自动生成的结果。

隐私与安全

• 所有扫描、索引和输出都保存在本机。
• 不上传文件内容、文件名、目录路径或扫描结果。
• large 浏览服务只绑定 127.0.0.1，不监听局域网或公网地址。
• large 数据通过本机服务按需读取，不会把完整数据库或全部节点嵌入浏览页面。
• 当前 Windows EXE 尚未进行代码签名，Windows 可能显示来源或安全提示。请只从正式公开项目的 Release 下载发布包。

输出位置

源码运行：

<项目目录>\outputs\

Windows EXE：

%LOCALAPPDATA%\FolderVisualizer\outputs\

标准工作流会生成：

• 通用：scan-result.json
• small：tree.html、exports/<目录名>-tree.svg
• large：folder-index.db、manifest.json

large 页面下载的当前路径 SVG 由浏览器保存到浏览器的默认下载位置。再次分析时，固定名称的输出文件可能被覆盖。

工作原理

flowchart LR
    A["选择文件夹"] --> B["扫描目录"]
    B --> C{"自动选择模式"}
    C -->|"small"| D["完整横向文件树"]
    C -->|"large"| E["本地索引"]
    E --> F["127.0.0.1 按需分页浏览"]

Loading

GUI 和 CLI 共用 workflow.py。扫描器、模式选择、结果生成和 large 服务生命周期保持分离，GUI 只负责选择目录、显示状态和打开结果。

当前限制

• 当前主要面向 Windows。
• 扫描结果是生成时的快照，不会实时跟踪磁盘变化。
• 无权限访问或扫描过程中消失的文件可能不会进入最终结果。
• 符号链接和目录联接不会递归进入。
• small 模式会完整生成并渲染所有节点，不适合超大目录。
• large 模式暂不支持全局搜索。
• large 当前路径 SVG 只包含路径链和当前页，不是完整子树导出。
• 关闭 GUI 后 large 本地服务会停止，已打开的 large 页面将无法继续读取目录。
• 文件类型按最后一个扩展名判断，例如 archive.tar.gz会归类为 .gz。
• SVG 中文文字外观取决于查看设备安装的字体。
• 当前不提供单文件 EXE、安装程序、CLI EXE、拖拽、PNG 或 PDF 导出。
• 当前 Windows EXE 尚未代码签名。

完整使用说明

下载、解压、small/large 操作、输出位置和常见问题请参阅：

完整使用说明