一个优雅、高辨识度且即开即用的静态网页、单页报告、前端 Demo 集中管理与沉浸式预览工作台。
支持单文件 HTML 报告与多层级多文件站点，提供「纯静态零成本托管」与「Cloudflare 免费云端托管」双通道架构。
- 双通道架构，自由选择
- 纯静态模式：无需任何后端、数据库或云服务器，丢入 HTML 即可自动生成目录与索引，100% 本地化运行，零门槛、零费用。
- 云端托管模式：基于 Cloudflare 免费全家桶（Workers + R2 对象存储 + KV 缓存），支持多端在线上传、增量添加文件与跨设备同步。
- 全屏沉浸式预览工作台
- 标准屏幕比例：内置标准桌面（1440 × 900 · 16:10）、全高清大屏（1920 × 1080 · 16:9）、移动端（375 × 812 · 手机）与流式铺满等真实屏幕视口。
- 智能等比缩放：页面内容自动适应屏幕大小，支持手动微调放大/缩小（20% ~ 150%）与无损刷新。
- 固定入口预览：左侧文件目录树浏览，右侧稳态预览站点主入口，告别传统弹窗的狭窄压抑。
- 强大的文件与站点管理
- 支持多文件与目录上传：支持单文件、多文件组合挑选，以及直接拖拽完整站点文件夹（保留 CSS、JS 等相对路径结构）。
- 智能主入口探测：自动识别
index.html或首选 HTML 文件作为项目入口。 - 本地只读安全保护：本地静态项目自动开启只读保护，展示完整文件明细与大小统计，避免在线误删本地文件。
- 云端项目一键下载：单文件项目直接下载原 HTML 文件，多文件项目自动打包为 ZIP，完整保留目录结构。
- 项目简介（README）：项目根目录的
README.md/readme.md会在预览工作台左侧渲染为项目简介，默认展示，可一键切回文件管理。
- 极简专业交互
- 纯矢量图标设计（
@vicons/ionicons5），无杂质视觉干扰。 - 支持按项目名、分类实时模糊搜索与分类聚合导航。
- 纯矢量图标设计（
- 版本系统与更新日志
- 每个版本号、发布日期与全部变更条目集中维护，站内「更新日志」页面按时间线完整呈现。
- 支持按新功能 / 修复 / 视觉 / 重构等类型筛选，侧边栏与顶栏实时提示未读新版本。
请根据你的实际使用场景选择以下任意一种部署方式：
- 方式一：纯静态极简部署（新手推荐 · 零成本）：适合个人本地整理、内网查看，或直接推送到 GitHub Pages / Vercel 等免费静态托管平台。
- 方式二：全功能云端部署（Cloudflare 免费全家桶）：适合需要登录管理后台、在线上传/删除项目、多人协作或跨设备访问。
完全不需要配置任何云服务或后端数据库，从克隆到运行仅需 1 分钟！
git clone https://github.com/zaneven/HTMLhub.git
cd HTMLhub
npm install将需要展示的 HTML 单文件或完整站点文件夹放入 public/html-files/ 下的对应分类文件夹中：
public/html-files/
├── 报告总结/
│ └── 哈基米文化研究.html
└── 可视化项目/
└── 数据大屏演示/
├── index.html
├── css/
└── js/
提示：文件夹名即为分类名称（如“报告总结”、“可视化项目”）。如需增加新分类，直接新建一个文件夹即可。
npm run scan此命令会自动递归扫描
public/html-files/，识别单文件与多文件项目，收集文件数量、体积与类型，并生成public/data/file-index.json。
-
本地启动预览：
npm run dev
在浏览器中打开终端显示的本地地址（如
http://localhost:5173）即可使用。 -
一键构建生产包：
npm run build
生成的
dist/文件夹为纯静态文件，可直接拖入 Vercel、Netlify、Cloudflare Pages 或 GitHub Pages，完全免费！
使用 Cloudflare Workers + R2 对象存储 + KV 缓存，免费额度完全覆盖个人和小团队的日常使用。
npm install -g wrangler
wrangler login# 1. 创建 R2 文件存储桶
wrangler r2 bucket create htmlhub-files
# 2. 创建 KV 缓存命名空间（注意记下终端输出的 id）
wrangler kv namespace create FILE_INDEX执行第 2 步后，终端会输出类似：
[[kv_namespaces]]
binding = "FILE_INDEX"
id = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
打开 workers/wrangler.toml 文件，将上述生成的 id 替换到 [[kv_namespaces]] 的 id 字段中。
cd workers
# 设置登录密码（根据提示输入你自定义的管理员密码）
npx wrangler secret put ADMIN_PASSWORD
# 一键部署 API 后端
npx wrangler deploy部署成功后，终端会打印出后端 API 访问地址，例如：
https://htmlhub-api.<你的账号>.workers.dev
返回项目根目录，从模板复制 .env 文件：
cd ..
cp .env.example .env打开 .env 文件，填入第 3 步生成的后端 API 地址：
VITE_API_URL=https://htmlhub-api.<你的账号>.workers.dev现在启动前端：
npm run dev在浏览器中打开，点击右上角「登录」，输入你在第 3 步设置的密码，即可体验完整的多文件上传、文件夹拖拽、在线增删及实时云端同步功能！
本系统采用单管理员密码认证机制，无需输入用户名/账号。
- 密码在部署后端时通过
npx wrangler secret put ADMIN_PASSWORD命令设置；- 如果需要修改密码，重新执行该命令输入新密码即可秒级生效，无需重新部署。
可以！ 系统支持双通道混合展现。如果配置了云端 API，首页会同时聚合显示本地已扫描的项目和云端 R2 中的项目：
- 本地静态项目：标记为
本地静态 (只读)，可以在线查看完整文件树与预览页面，但前端无法也禁止在线增删本地磁盘文件，保证本地资产安全；- 云端项目：标记为
云端 R2，支持在线追加文件、上传新版本和删除。
系统会自动在上传的文件列表中查找
index.html或首选 HTML 文件作为主入口。进入全屏工作台后，右侧会自动呈现该入口的渲染结果。
如果你有自己在 Cloudflare 托管的域名，只需编辑
workers/wrangler.toml，取消routes注释并填入你的域名：routes = [ { pattern = "api.yourdomain.com", custom_domain = true } ]然后重新执行
npx wrangler deploy即可自动完成 SSL 证书签发与 DNS 解析。
| 命令 | 说明 |
|---|---|
npm run dev |
启动本地开发热重载服务器 |
npm run scan |
扫描本地 public/html-files/ 生成静态索引数据 |
npm run build |
执行严格 TypeScript 类型检查并构建生产静态包 |
npm run lint |
运行 ESLint 进行代码规范检查与自动修正 |
npm run type-check |
执行 Vue 与 TypeScript 静态类型检查 |
npm run test |
运行单元测试（含版本记录一致性校验） |
npm run test:run |
单次执行全部单元测试（适用于 CI） |
当前版本 v1.2.0。每次迭代的变更内容统一记录在 src/data/changelog.ts，站内访问 /changelog 即可查看完整版本时间线。
发布新版本的步骤、记录规范与自动化校验说明见 docs/versioning.md。
html-manager/
├── public/
│ ├── data/
│ │ └── file-index.json # 扫描生成的本地项目索引文件
│ └── html-files/ # 本地静态 HTML 项目分类存放目录
├── src/
│ ├── components/
│ │ ├── admin/ # 项目全屏预览与文件管理工作台
│ │ ├── files/ # 项目卡片、上传弹窗与视图组件
│ │ └── layout/ # 顶部导航、侧边栏及主布局
│ ├── stores/ # Pinia 状态中心（文件列表、搜索、鉴权）
│ ├── data/ # 版本清单与更新日志数据源
│ ├── composables/ # 组合式函数（搜索、文件、模式、版本未读状态）
│ ├── views/ # 页面视图（首页、分类、更新日志、设置、登录、管理后台）
│ ├── types/ # TypeScript 类型定义
│ └── utils/ # 文件识别与工具库
├── workers/ # Cloudflare Workers API 与 R2 存储后端
│ ├── src/ # 后端接口与鉴权逻辑
│ ├── wrangler.toml # Cloudflare 配置文件
│ └── wrangler.toml.example # 开源通用配置模板
├── scripts/
│ └── scan-files.js # 本地项目递归扫描生成脚本
└── vite.config.ts # Vite 构建配置文件
本项目基于 MIT License 协议开源。