mshen6666/HTML-PPT-Editor 教程

安装 mshen6666/HTML-PPT-Editor 时，需要明确它不是单页 HTML 工具或传统 PPT 插件。它是 React 19、TypeScript、Vite 和 Express 5 组成的 Web 应用，本地开发要让前端和后端一起运行；只打开 index.html 看不到完整编辑、导出和 Agent 能力。

这个项目的价值在于把可编辑 HTML deck 当作核心数据源，提供文字、图片、布局、图层、动效元数据、页面结构编辑，以及 HTML、PDF、截图栅格化 PPTX 导出。它的限制也很明确：AI Agent、上传、会话、邀请码门禁和运行时目录都依赖后端配置，不能只按静态站点部署。

本地最快启动方式

仓库默认分支是 main。先 clone，再安装依赖：

git clone https://github.com/mshen6666/HTML-PPT-Editor.git
cd HTML-PPT-Editor
npm install

开发时推荐直接启动全套服务：

npm run dev:full

这个命令会同时启动 Vite 前端和 Express API 服务。本地开发时，前端会把 /api 请求代理到 127.0.0.1:8787。如果想分开看日志，也可以分别运行：

npm run dev
npm run dev:server

打开后先理解 deck contract

HTML-PPT-Editor 的核心不是上传 PPTX 后直接改，而是把 HTML deck 规范化为可编辑结构。源码里有 src/deck-contract/，负责 HTML deck 解析、补丁和序列化；src/app/ 和 src/app/editor/ 则承担编辑器界面和控制逻辑。

项目内置 html-ppt 模板与主题资源，也接入了 beautiful-html-templates 模板库。HTML PPT 指南里能浏览主题、模板、布局和动效，帮助在生成或编辑文稿前先确定视觉方向。

导出路径也围绕 HTML deck 展开：src/export-html/、src/export-pdf/、src/export-pptx/ 和 src/export-runtime/ 分别负责不同产物。PPTX 导出是基于截图栅格化的结果，不等于把每个 HTML 元素恢复成可编辑 PowerPoint 形状。

生产配置别跳过 .env

生产部署或启用 AI 工作流前，先复制示例环境文件：

cp .env.production.example .env.production

示例里包含 PORT、PPT_INVITE_CODE、PPT_INVITE_COOKIE_SECRET、PPT_SANDBOX_ROOT、PPT_ARTIFACT_ROOT、PPT_UPLOAD_ROOT，以及 Claude Code 兼容 provider 的 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL。

邀请码门禁在 Express 层生效。文档明确提醒，不要绕过 Node/Express 直接暴露 dist/ 静态目录，否则浏览器能拿到前端资源，门禁也会失去意义。

生产启动和健康检查

生产侧推荐单体 Node 应用部署：

npm ci
npm run build
npm start

当 dist/ 存在时，Express 会同时提供前端页面和 /api/* 接口。启动后可检查：

curl http://127.0.0.1:8787/api/health

预期返回 { "ok": true }。如果缺少 dist/，后端 API 仍能启动，但不会提供浏览器端应用。

本地验证命令

改动前后建议跑测试和构建：

npm test
npm run build

CHANGELOG 中 2026-05-16 的记录显示，项目接入 beautiful-html-templates 后曾通过 28 个测试文件、208 个测试，并通过构建。涉及 deck 编辑、序列化、预览布局、Agent 协议或导出行为时，更应该补对应回归测试。

适合的使用边界

mshen6666/HTML-PPT-Editor 适合需要在浏览器里维护 HTML 演示稿、做可视化编辑、导出 HTML/PDF/PPTX，并保留可选 AI Agent 起稿的团队。它比单纯 HTML 模板库重，但也提供了编辑器、后端 API、门禁、上传和运行时存储。

如果只想把一个现成 HTML 文件截图成 PPTX，这个项目会显得过重；如果需要可编辑 HTML deck 的长期工作台，它的前后端结构、deck contract 和导出模块就正好对口。安装时先让 npm run dev:full 跑通，再考虑生产环境变量和 Agent provider 配置，会少走很多弯路。