BOOKpandoc开发日志和.NET桌面应用开发笔记

起因只是在我小红书分享了一个用 CSS 为 OC 小说制作“纸质书”风格主题的Pandoc教程，意外走红。许多用户留言表示想学且希望能有一个图形化工具。于是我做了一个基于Pandoc的将 Markdown 文件一键转换成带精美排版的电子书（EPUB、HTML 等）的Windows桌面应用BOOKpandoc——假装出书。

仓库地址：Morlvoid/BOOKpandoc

附录：开发资源

• 主仓库：https://github.com/Morlvoid/BOOKpandoc
• 主题仓库：https://github.com/Morlvoid/BOOKpandoc-themes
• 官网：http://bookpandoc.morlvoid.pro/
• 内测群：QQ 1085968983
• 安装包下载：https://github.com/Morlvoid/BOOKpandoc/releases

（嗯对附录就是放在最前面）

BOOKpandoc——假装出书

项目信息	内容
中文名	假装出书
英文名	BOOKpandoc
核心功能	将多章节 Markdown 文件一键生成 EPUB/Word/HTML 电子书，支持拖拽排序、自定义主题
目标用户	OC 创作者、同人写手、小说爱好者（非技术背景）
开发平台	Windows 10/11
开发工具	Visual Studio 2022 Community

核心需求

基础功能（v1.0）

• 支持拖拽添加 .md 文件
• 书名/作者输入
• 章节列表支持拖拽排序
• 支持从列表移除章节
• 封面图片选择
• 选择导出格式（EPUB, DOCX, HTML, PDF）
• 选择输出目录（默认桌面或文档）
• 选择 CSS 主题（内置的小说主题）
• 支持拖拽导入 .css 文件作为新主题
• 点击“生成书籍”，异步执行 pandoc，显示进度/结果
• 检测 PDF 导出时是否安装 LaTeX，未安装则友好提示
• 错误信息清晰易懂（不显示技术报错）
• 最近使用主题记忆
• 转换历史记录

技术选型

略懂一点C++，Java 后端背景，桌面开发零经验。经过一番调研，我选择了：

类型	选型	理由
界面框架	WPF	数据绑定方便，适合桌面应用
编程语言	C#	语法与 Java 接近，上手快
目标框架	.NET 6.0 (LTS)	独立发布后可自带运行时，用户无需安装 .NET
文档转换引擎	Pandoc	开源、强大，支持多种格式
拖拽排序	GongSolutions.Wpf.DragDrop	免费、简单，一行代码实现拖拽
安装包制作	Inno Setup	免费，可创建桌面快捷方式、开始菜单
版本控制	Git + GitHub	开源托管，Releases 分发安装包
官网	静态 HTML/CSS	展示功能、下载链接
主题管理	独立 GitHub 仓库 + PR	低成本社区共建

---

开发过程

1. 需求细化与界面设计

• 用Canva可画设计出主要界面：左侧下载列表、中间文件预览区域、右侧设置区域、上方书名/作者、下方格式/主题/封面/输出目录、底部导出按钮。

• 列出需要实现的功能点。

• 确定了基本功能：文件拖拽添加、拖拽排序、EPUB/HTML 导出、主题选择、PDF 检测、日志记录。

2. 搭建环境

• 安装 Visual Studio 2022 Community，选择“.NET 桌面开发”。
• 新建 WPF 项目，目标 .NET 6.0。
• 通过 NuGet 安装 GongSolutions.WPF.DragDrop。
• 在项目根目录创建 themes 文件夹，放入自己写的小说主题 default.css。
• 下载 pandoc.exe 用于本地测试。

3. 核心功能实现

数据模型

public class Chapter
{
    public string FilePath { get; set; }
    public string FileName => System.IO.Path.GetFileName(FilePath);
}

Pandoc 调用服务

封装了 PandocService.ConvertAsync，根据不同格式动态构建参数：

• HTML 添加 --self-contained 将 CSS 内嵌；
• EPUB 使用 --css；
• DOCX 检测 rsvg-convert 是否存在；
• PDF 检测 LaTeX 环境。

拖拽添加与排序

• 在 ListBox 上处理 DragOver 和 Drop，实现文件拖入添加。
• 使用 GongSolutions.Wpf.DragDrop 实现内部拖拽排序（只需绑定 IDropTarget 接口）。

主题管理

ThemeService 扫描 themes 文件夹，支持拖入 CSS 文件自动复制并刷新下拉框。

日志服务

自写 LogService，记录运行信息，便于调试和用户反馈。

4. 踩坑实录

坑 1：HTML 封面无法显示

我想把用户选择的封面图片作为 #title-block-header 的背景图，但用 --include-before-body 插入的 <div> 跑到了正文前面，破坏了结构。
解决：改用 --include-in-header 动态生成内联样式，设置背景图。

坑 2：EPUB 样式参数过时

报错：--epub-stylesheet has been removed. Use --css instead.
解决：统一使用 --css 参数，EPUB 也能正常应用样式。

坑 3：DOCX 导出 SVG 失败

用户文档里如果有 SVG 图片，Pandoc 需要 rsvg-convert 工具。
解决：增加检测，提示用户安装 librsvg 或手动下载。

坑 4：朋友反馈“无法运行，缺少 .NET”

第一次发布时采用了框架依赖部署（Framework-Dependent），朋友双击后报错“缺少 .NET 6.0 运行时”。原来用户需要自己安装 .NET，这显然不符合“开箱即用”的预期。
解决：改用独立部署（Self-Contained）模式，将 .NET 运行时一起打包进去。虽然安装包体积从 20MB 涨到 70MB，但终于能双击直接运行了。

坑 5：标题栏按钮时灵时不灵

最小化、最大化、关闭按钮经常无效，查了半天才发现 XAML 里忘了绑定 Click 事件。
解决：给三个按钮加上 Click="MinimizeButton_Click" 等，事件立马生效。

坑 6：Pandoc 检测总是失败

电脑明明装了 Pandoc，但 IsPandocInstalled() 总是返回 false。
解决：改进检测逻辑，先尝试从 PATH 执行 pandoc --version，再检查常见安装路径（C:\Program Files\Pandoc 等），并加入日志输出定位问题。

打包与发布

1. 生成独立发布文件夹

dotnet publish -c Release -r win-x64 --self-contained true -p:PublishSingleFile=false

2. 编写 Inno Setup 脚本

指定要打包的文件（exe、dll、pandoc.exe、themes 等），创建桌面快捷方式和开始菜单项。

3. 编译安装包

在 Inno Setup 中打开脚本编译，得到 BOOKpandoc_Setup.exe。

4. 上传到 GitHub Releases

• 创建新 Release，版本号 v1.0.0。
• 上传安装包，附更新日志。
• 发布后，用户即可在 Releases 页面下载。

---

社区与开源

官网

建立了简洁的官网：bookpandoc.morlvoid.pro/，展示功能、截图、下载链接。

主题仓库

创建了独立的 GitHub 仓库 BOOKpandoc-themes，鼓励社区提交 CSS 主题和设计稿，通过 PR 审核合并。

目前的测试内置主题：

内测群

建立了 QQ 群（群号 1085968983），邀请小红书粉丝内测，收集反馈。

---

后续更新

v1.0 已经实现了：

• ✅ 拖拽添加 .md 文件
• ✅ 章节拖拽排序
• ✅ 书名/作者输入
• ✅ 封面图片（HTML/EPUB）
• ✅ 输出格式（EPUB、HTML、PDF、DOCX 基础支持）
• ✅ 自定义 CSS 主题（内置小说主题）
• ✅ 日志记录

但还有很多不足：

• DOCX 样式依赖参考文档模板，需要用户自己准备；
• PDF 导出需要 LaTeX 环境，目前只做检测提示；
• 应用内主题市场尚未开发；
• 内置编辑器暂不支持。

.NET小白抛砖引玉一下qwq希望社区的大佬们能一起来完善这些功能。如果对 C#/WPF 熟悉，欢迎提 PR；如果擅长 CSS，欢迎贡献主题。

学习日志

这次最大的收货是跑通了从设计到编写到发布部署开源的完整流程：

C# / .NET 桌面应用开发与交付流程（大概）

1. 需求与设计阶段
2. 版本控制初始化（建立仓库，设置.gitignore）
3. 开发阶段（编码，同时实现异常处理和日志记录）
4. 本地测试与调试
5. 跨环境测试与发布准备
6. 打包与安装包制作
7. 部署与发布

1. 需求分析与设计

• 明确功能：梳理核心功能、用户场景，必要时画流程图。
• 技术选型：选择 WPF / WinForms，确定 .NET 版本（ .NET 6.0）。
• 界面设计：绘制页面草图或使用原型工具，规划交互逻辑。

2. 版本控制初始化（建立仓库）

• 创建远程仓库：在 GitHub新建空仓库。
• 本地初始化：
  • 在项目根目录执行 git init
  • 添加 .gitignore（使用 C# 模板，排除 bin/, obj/, packages/, .vs/ 等）

3. 开发（含异常处理与日志）

• 编码实现：按模块或功能逐步实现。
• 异常处理：
  • 在关键操作（文件读写、网络请求、数据库连接）处使用 try-catch，捕获异常后向用户提示友好信息。
  • 避免“吞掉”异常，应记录日志或抛出到上层统一处理。
• 日志记录：
  • 引入日志库（如 Serilog、NLog 或 Microsoft.Extensions.Logging）。
  • 记录关键节点（启动、关闭、重要操作成功/失败）和异常详情。
  • 日志可输出到文件、控制台或系统事件日志。
• 配置管理：
  • 使用配置文件（appsettings.json 或 App.config）存放环境相关参数。
  • 区分开发/生产配置，避免硬编码密码等敏感信息。

4. 本地测试与调试

• Debug 模式测试：在开发环境中运行，验证功能是否符合预期。
• 单元测试（可选）：对核心逻辑编写测试项目，提高代码可靠性。
• 异常和日志验证：触发错误场景，检查日志是否正常记录，异常处理是否符合预期。

5. 跨环境测试（准备发布）

• 切换 Release 模式：在 Visual Studio 中将解决方案配置改为 Release。
• 独立发布测试：
  • 使用 dotnet publish 或 VS 发布功能，选择“独立”部署（--self-contained true）并指定目标平台（如 win-x64）。
  • 将发布后的文件夹复制到一台 未安装 .NET 开发环境 的虚拟机或备用电脑上运行，验证依赖是否齐全，界面和功能是否正常。
• 兼容性测试：如果目标用户可能使用不同 Windows 版本，尽可能多测试几个环境（如 Win10、Win11）。

6. 打包与制作安装包

• 清理：删除发布文件夹中不必要的调试文件（发布时选择 Release 会自动排除）。
• 选择安装包工具：
  • Inno Setup / InstallShield：功能强大，可定制安装过程（创建桌面快捷方式、注册表操作等）。
• 生成安装包：将发布输出打包成一个 .exe 安装文件。

7. 部署与发布

• 交付安装包：将安装包上传到网盘、官网下载页或企业内部共享位置。
• 用户安装：提供简单的安装说明（如有特殊依赖，提前告知）。
• 后续维护：
  • 保留源码和安装包版本记录。
  • 若使用 ClickOnce 或 MSIX，可配置更新地址实现自动升级。
  • 根据用户反馈修复 Bug，通过 Git 分支管理新版本开发。

流程示意图（文字版）

需求设计 → 版本控制（初始化仓库）→ 编码开发（含异常处理+日志）→ 本地Debug测试
    ↓
跨环境Release测试（干净虚拟机）→ 制作安装包 → 部署发布 → 维护迭代

步骤	说明
1. 需求与设计	明确功能，设计界面（WPF/WinForms），确定依赖（Pandoc、LaTeX 等）。
2. 编写源码	在 Visual Studio 中开发，使用 .NET 6/8，本地调试运行。
3. 异常处理与日志	添加 try-catch，记录日志（便于用户反馈时定位问题）。
4. 本地测试	在自己电脑上反复测试各种场景（正常流程、异常输入、路径含空格等）。
5. 多环境测试	非常重要：找几台配置不同的电脑（如未装 .NET、未装 Pandoc、Win10/Win11 等）测试，确保“我的电脑能跑，别人也能跑”。
6. 清理与归档源码	提交到 GitHub（开源）
7. 制作发布包	使用 dotnet publish --self-contained true 生成独立程序包（自带 .NET 运行时），然后打包成安装程序（Inno Setup）或便携版 zip。
8. 分发与更新	将安装包上传到 GitHub Releases，用户下载安装即可。后续通过 Release 更新版本。

• 独立发布：必须用 --self-contained true，否则用户需要自己装 .NET 运行时。这样生成的程序体积虽大（约 70-100 MB），但用户双击即用，体验最好。
• Pandoc 处理：可以选择在安装包里附带 pandoc.exe（增加体积但省心），或者让程序首次运行时自动下载（已实现 winget 方式）。建议优先用自动下载，减少安装包体积。
• 测试环境：务必在 未安装 .NET 6、未安装 Pandoc 的干净系统上测试独立发布版，确保不报错。
• 安装包：用 Inno Setup 制作，可自动创建桌面快捷方式、开始菜单项，并可选择将 pandoc.exe 一同打包。
• 开源规范：源码仓库只放代码和文档，不放编译产物、不放大的二进制文件（如 pandoc.exe）。发布包放在 Releases 页面，供普通用户下载。