# epubStudio

**Repository Path**: xuhongling/epub-studio

## Basic Information

- **Project Name**: epubStudio
- **Description**: epub电子书编辑器
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-29
- **Last Updated**: 2026-11-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EPUB Studio

Electron + Vue 3 + TypeScript 的 EPUB 编辑器。代码视图是唯一真相，预览与样式面板负责降低
「改排版」的门槛；面向「把已经做好的书改一改再发回去」的场景。

- 架构说明：[`docs/architecture.md`](docs/architecture.md)
- 长期路线图：[`docs/roadmap.md`](docs/roadmap.md)

## 技术栈

| 能力 | 选型 |
|---|---|
| 壳 | Electron（main / preload / renderer 三层，contextIsolation 开） |
| UI | Vue 3 `<script setup>` + TypeScript + Pinia + SCSS（Dart Sass） |
| 构建 | electron-vite + Vite |
| 编辑器 | CodeMirror 6（XHTML / CSS / XML 按扩展名切换） |
| 解包 / 回写 | fflate（mimetype 保证第一个且不压缩） |
| OPF 解析 | fast-xml-parser（`removeNSPrefix`，不依赖 DOMParser） |
| 预览 | iframe srcdoc，本书 CSS 内联、图片转 data URL、正文带源码偏移、`sandbox` 禁脚本 |
| 校验 | 官方 EPUBCheck 5.4（TeaVM 版，免 Java），跑在 utilityProcess |
| 样式抽屉 | shadow DOM + `adoptedStyleSheets`，每条规则真渲染 |

## 跑起来

主推 **pnpm**（仓库里的锁文件是 `pnpm-lock.yaml`）：

```bash
pnpm install
pnpm dev
```

`npm install` 也能用（会自己生成 `package-lock.json`），但两套锁文件不要同时提交。

### 依赖安装脚本的放行（pnpm 10+ 必看）

pnpm 10 起默认**不执行**依赖的 install/postinstall 脚本，而 Electron 的二进制正是靠
`install.js` 下载的。放行配置写在 `pnpm-workspace.yaml`：

```yaml
allowBuilds:
  electron: true     # 下载对应平台的二进制
  esbuild: true      # 下载平台专用二进制
  vue-demi: true     # 按 Vue 版本切入口（pinia 依赖）
```

> pnpm 11 不再读 `package.json` 里的 `pnpm.onlyBuiltDependencies`，配置已迁到
> `pnpm-workspace.yaml`。如果你在旧版本上装过依赖，改成上面这样后需要重装一次。

### 启动报错先看这里

**`Error: Electron uninstall`** —— 包在、二进制不在（`node_modules/electron/dist` 为空）。

常见成因是 pnpm 的「重新链接」：它从内容寻址仓库还原包文件时，不会带上
postinstall 下载出来的 `dist/`，但 pnpm 又记着这个包已经构建过，不会重跑 `install.js`。
所以换锁文件、`--force`、清过 node_modules 之后都可能踩到，而且**重装依赖也修不好**。

现在启动器会自愈：`pnpm dev` / `pnpm start` 在拉起 Electron 前会先跑
`scripts/ensure-electron.mjs`，缺了就按镜像补装，日志里能看到

```
[ensure-electron] 二进制已就绪        # 正常
[ensure-electron] 二进制缺失，开始补装  # 自动修
```

如果补装失败（离线 / 镜像不通），手动补一次即可：

```bash
node node_modules/electron/install.js
# 或显式指定镜像
ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ node node_modules/electron/install.js
```

仓库已配好 `.npmrc`（registry 与 electron 二进制都走国内镜像）。

**`Cannot read properties of undefined (reading 'whenReady')`** —— Electron 退化成了纯 Node，
几乎必然是环境变量 `ELECTRON_RUN_AS_NODE=1`（某些 Electron 宿主会注入给所有子进程）。
`pnpm dev` / `pnpm start` 走 `scripts/launch.cjs`，启动前会自动删掉它。

手动启动时：

```bash
env -u ELECTRON_RUN_AS_NODE ./node_modules/.bin/electron .   # Git Bash / macOS
```

## 常用命令

pnpm 与 npm 都能跑（`pnpm dev` ≈ `npm run dev`）。

| 命令 | 作用 |
|---|---|
| `pnpm dev` | 开发模式（HMR） |
| `pnpm build` | 构建到 `out/` |
| `pnpm start` | 以生产产物启动 |
| `pnpm typecheck` | 渲染层 + 主进程全量类型检查 |
| `pnpm test` | 纯域单元测试（90 例） |
| `pnpm smoke` | 真实 epub 解析 → 回写 → 再解析 |
| `pnpm selfcheck` | 启动真实 Electron，打开样例书并断言界面渲染 |

`pnpm smoke` 会依次找 `argv[2]` → `.tmp/sample.epub` → `.tmp/` 下任意 epub；
都没有就跳过。指定样例：`pnpm smoke -- path/to/book.epub`。

## 目录结构

```
src/
├── shared/     类型 + IPC 契约 + 路径/文本工具（零运行时依赖）
├── main/       主进程：app（窗口/菜单）· ipc（路由）· services（领域）· workers
├── preload/    契约 → window.epub，信封 → 带 code 的异常
└── renderer/
    ├── app/        命令总线 · 菜单桥 · 快捷键 · 用例编排
    ├── core/       纯域：epub（toc/meta/roles）· css · html
    ├── editor/     CodeMirror 适配（host / source / commands / theme）
    ├── stores/     book · tabs · ui · style · preview · validation · history
    ├── features/   book-tree · editor · tabs · preview · styles · snippets ·
    │               toc · search · validate · dialogs · workspace
    └── components/ui/
```

**依赖方向**：`core → stores → features → app`，`shared` 被两侧共享。
`core/` 不允许 import Vue / Electron / CodeMirror —— 它是可单测的地基。

## 这一版做了什么（相对重构前）

结构层面的重排，行为保持不变：

1. **主进程从 484 行单体拆成服务层**：`BookSession`（唯一的书稿状态）、
   `ValidationService`（worker 生命周期与取消语义）、`ProjectRepository`、
   `RecentStore`、`SettingsStore`、`epub/*`（容器 / OPF / 模板 / 新建）。
2. **IPC 有契约了**：通道名、请求体、响应体集中在 `shared/ipc/contract.ts`，
   主进程 `handle()` 与 preload `invoke()` 都从它推导；错误统一信封 + 错误码。
3. **一个 40 字段的全局 state 拆成 7 个 Pinia store**，边界按「谁拥有这份数据」划分。
4. **命令总线**：菜单、快捷键、右键菜单、按钮发同一个命令 id，可用性只判断一次。
5. **CodeMirror 隔离成适配层**：`host`（生命周期）/ `source`（按偏移读写）/
   `commands`（业务决策）/ `tags`（标签分类）。
6. **预览拆出 `render.ts` 与 `decorate.ts`**：HTML 生成与「阅读器外壳」装饰各自独立。
7. **质量门禁**：类型检查 + 90 例单测 + 冒烟 + 端到端自检。

重构中顺带修掉的真实缺陷：**样式表以 `@charset` 开头时，第一条规则会被样式抽屉静默丢掉**
（`parseRules` 把 at-语句当成了规则前导段）。已有回归测试覆盖。

## 已实现的功能

- 打开 / 新建（空白或模板）/ 另存为 / 工程目录模式（解包、打包）
- 命令面板（`Ctrl+P`），左右栏可折叠并记忆布局；启动页支持最近打开
- 关键操作 Toast 通知、错误详情复制，以及切换图书 / 关闭窗口时的未保存改动保护
- 资源树右键：新增章节、新增全屏插图页、导入、删除（联动清理全书引用）、重命名（联动
  href/src/url()）、封面、全屏页标记
- 多标签编辑，每标签独立光标、滚动、撤销栈；关闭标签不丢改动
- 选中 CSS、图片、字体或 XML 等非正文资源时自动切到代码视图，直接显示源码或二进制内容
- 样式抽屉：按区域 / 段落 / 文字分组，逐条真渲染；**单击即套用**，悬停会在预览里框出命中元素
- 图书视图：打开图书默认进入，CSS 内联、图片转 data URL、双击原地改字、语义块属性卡；
  单击选择段落，`Ctrl/Cmd+点击` 多选块，右侧样式可批量套用并作为一次操作整体撤销；
  **鼠标拖选文字后点「文字样式」只给选中的字加行内 class**（跨段落逐段包 `span`，
  等价于 Word 的字符样式），重绘后选区自动接回，可连续叠第二条；选中块时工具条同时显示
  CSS 抽屉里那条规则的中文描述
- 多看语义块：画廊、脚注、代码块、交互图、交互式表格、音视频、习题、首字下沉、公式
- 目录：从标题生成（NCX + nav）、可视化编辑（拖拽排序、层级调整、批量操作）
- 章节结构：在光标处拆分、按 Dobby 章节标记一键分割成多章、与前一个章节合并（均联动
  manifest / spine / 目录锚点，可整体撤销）；「智能标记章节线」可先把脏稿标出章节边界
- 检查图书数据：未用文件 / 未用样式 / 引用了但不在 manifest 的文件，未用文件可就地删除
- 排版批处理：去除多余空格、中文双引号、换段转换行、清理空段落（全书执行，可整体撤销）
- 批量重命名 / 批量插入 ID：按规则重命名全书资源（联动 manifest / spine / 全部引用），
  给没有 id 的段落批量补锚点，序号跨文件连续
- 设备模拟预览：Kindle（540×720 排版视口，墨水屏黑白 + 纸色颗粒）/ iPad / iPhone / 安卓平板，
  按机型宽度排版并等比缩放
- 片段库：内置 22 个多看语义块 + 3 个章节页模板，用户可增删改、分组管理；
  右键章节可选「从模板新增」，`{{title}}` 自动换成章节标题
- 自动修复（Mend）：补未闭合标签、删孤立结束标签、空元素自闭合、属性补引号、转义裸 `&`，
  每项可单独开关，只做确定性修复，应用后可整体撤销
- 全书正则替换（实时预览命中数，可撤销）
- EPUBCheck 校验（流式结果、可取消、结果可跳转）
- 跨文件撤销 / 重做（与编辑器逐字撤销按时间合并调度）
- 代码补全：本书类名、书内路径、`epub:type`
- 粘贴纯文本自动分段（区分网页复制与老式 TXT 硬换行）

## 快捷键

| 键 | 动作 |
|---|---|
| `Ctrl+O` / `Ctrl+S` / `Ctrl+Shift+S` | 打开 / 保存 / 另存为 |
| `Ctrl+N` | 新建图书 |
| `Ctrl+P` | 命令面板（搜索并执行全部功能） |
| `Ctrl+B` / `Ctrl+Alt+B` | 折叠左侧资源栏 / 右侧样式工具栏 |
| `Ctrl+T` / `Ctrl+H` | 目录 / 全书替换 |
| `Ctrl+W` / `Ctrl+Tab` / `Ctrl+Shift+Tab` | 关标签 / 前后切标签 |
| `F5` / `F3` | 代码视图 ⇄ 图书视图 |
| `Ctrl+Z` / `Ctrl+Shift+Z` | 撤销 / 重做（编辑器内逐字，外部走应用栈） |
| `Ctrl+Shift+P` | 文本转段落 |
| `Ctrl+Shift+K` / `Ctrl+Shift+J` | 在光标处拆分章节 / 与前一个章节合并 |

菜单加速键只在原生菜单注册 —— Electron 的菜单加速键不会吞掉页面按键，
两边都注册会一次按键执行两次。

## 许可

MIT