Folder City

一个基于 Python + Vue 实现的文件系统可视化工具，通过扫描文件夹元数据，将本地文件与目录渲染成 2.5D 动态城市，实现文件结构的直观、趣味化展示。

功能介绍

• 递归扫描本地文件夹，仅读取文件元数据，不读取文件内容
• 根据文件类型自动映射建筑样式：代码=办公楼、图片=画廊、视频=影院、音频=音乐厅、文档=图书馆、压缩包=仓库、其他=住宅
• 文件越大，建筑高度越高；文件越久未修改，建筑颜色越陈旧
• 实时展示文件总数、总大小、类型分布、跳过项统计
• 点击任意建筑可查看详细信息：路径、大小、修改时间、建筑类型
• 支持手动输入路径与系统目录选择弹窗两种启动方式

本地运行

后端启动

uv sync uv run python main.py

uv run python -m uvicorn backend.main:app –host 127.0.0.1 –port 8010 –reload

前端启动

cd frontend npm install npm run dev

自定义端口

$env:FOLDER_CITY_API_PORT=”8020” uv run python main.py

$env:VITE_API_TARGET=”http://127.0.0.1:8020" npm run dev

接口参数

{ “path”: “D:/Code/Python/Practice/folder-city” }

项目结构

folder-city/ ├─ backend/ # FastAPI backend & file scanner ├─ frontend/ # Vue + Vite 2.5D visualization ├─ tests/ # Backend unit tests ├─ main.py # Backend entry ├─ pyproject.toml # Python dependencies └─ README.md

测试与打包

uv run python -m unittest discover -s tests cd frontend npm run build