项目架构
BookX 的模块边界、工作区数据、静态构建和发布流程。
总览
BookX 的核心是 Go 静态站点构建器。命令行与桌面程序共用 internal/bookx/；桌面程序启动本机 HTTP 服务，在浏览器中运行 Vue 工作台。正式站点生成后只包含静态文件，不需要工作台或 Go 进程在线运行。
flowchart LR
CLI[bookx 命令行] --> Core[internal/bookx]
Desktop[bookx-desktop 托盘] --> Studio[internal/studio 本机服务]
Studio --> UI[嵌入的 Vue 工作台]
Studio --> Core
Files[bookx.yml · Markdown · 图片] --> Core
Themes[内置或自定义主题] --> Core
Core --> Output[dist 静态站点]
Output --> Publish[本地 · Git · SSH/SFTP]
代码分工
| 路径 | 职责 |
|---|---|
cmd/bookx/ | 命令行入口，支持的命令见下文。 |
cmd/bookx-desktop/、internal/desktop/ | 系统托盘、浏览器启动、工作区切换和桌面生命周期。 |
internal/studio/ | 本机 HTTP API、工作区管理、预览服务和嵌入式 Vue 页面。前端源码在 src/。 |
internal/bookx/ | 配置与内容读取、Markdown、安全过滤、路由、资源、主题、构建、同步和发布。 |
themes/ | Go HTML 模板、CSS、JavaScript 和内置主题清单。 |
build/ | 桌面安装包、图标及包验证脚本。 |
命令行入口
cmd/bookx/main.go 提供以下命令，桌面工作台通过同一套核心能力操作站点：
| 命令 | 用途 |
|---|---|
bookx init | 创建站点工作区与初始配置。 |
bookx new | 新建文章、文档合集、章节或文档页面。 |
bookx build | 生成静态站点，可选择包含草稿。 |
bookx validate | 检查内容并尝试构建，不替换正式站点输出。 |
bookx clean | 清理生成的站点文件。 |
bookx serve | 在本机提供站点预览服务。 |
bookx watch | 监测文件变化并重新构建。 |
bookx studio | 启动浏览器工作台的本机服务。 |
bookx sync | 同步工作区源码到 Git 远程仓库。 |
bookx publish | 重新构建公开站点并发布到指定目标，支持发布检查。 |
bookx version、bookx help | 查看版本和命令用法。 |
cmd/bookx-desktop/ 是单独的桌面托盘程序，负责启动和管理本地工作台。
internal/studio/dist/ 由 Vue 构建生成，Go 通过 embed 将其放进程序；themes/ 中的内置主题源码也会嵌入程序。源码检出后先在 internal/studio/ 运行 npm ci 和 npm run build，再执行 Go 构建或测试。不要手工编辑生成的 internal/studio/dist/。
工作区的数据边界
bookx.yml 保存站点地址、内容目录、主题、SEO 等可同步设置。博客和文档的 Markdown Front Matter 保存稳定 id、标题、可见性等内容信息。文档目录结构决定合集与章节关系；编译核心负责生成 URL 和导航树，主题只负责展示。
.bookx/local.yml 保存本机的 Git 同步、发布目标和工作台偏好。.bookx/ 下的回收站、预览和 SQLite 图片索引属于本地状态；图片索引可以从真实文件重建，不能当作内容来源。dist/ 是正式构建输出。
构建与预览
LoadConfig读取配置并确定工作区路径。- 内容加载器读取博客和文档，解析 Front Matter 与 Markdown，检查稳定 ID、可见性和路由，并建立文档树与内容资源关系。
- 主题加载器选择内置或工作区主题，准备模板及浏览器资源；构建器据此生成页面、搜索、归档、RSS 和站点地图。
build先写入临时目录，生成成功后替换已有的正式输出；validate在临时目录完成同样的生成检查，不替换正式输出。
本地“构建全部”使用独立的 .bookx/preview/，可查看草稿、私有和仅本地内容，并关闭评论与统计。正式发布总是重新生成公开站点。构建器提供统一的 URL 处理，主题和正文链接都要兼顾根域名与子路径部署。
同步与发布
源码同步处理工作区中的 Markdown、图片、配置与主题源文件；发布只处理公开静态产物。internal/bookx/deploy.go 实现 Git 同步和本地、Git、SSH/SFTP 发布目标。多目标发布先构建一次，再按选择顺序分别发布；某个目标失败不会撤销已经成功的目标。
扩展站点表现时，优先修改 themes/；新增内容关系、路由或构建规则时，修改 internal/bookx/ 并为主题提供明确的数据字段。具体的主题接口见主题设计，发布配置见同步与发布。
讨论这篇内容
评论由 GitHub Discussions 提供 · 打开讨论仓库