同步与发布

BookX 将“源码同步”和“站点发布”分开：前者保存文章、文档、图片、配置和主题源文件，后者上传公开构建后的网页。完成源码同步不会自动更新网站。

源码同步

打开工作台的“发布”页，在右侧展开“源码同步 · Git 工作区”，填写远程名称、HTTPS 仓库地址和分支。先点“查看状态”，确认工作区与远程仓库，再点“提交并同步”。遇到冲突时，按页面提示处理冲突文件后再同步；不要直接覆盖尚未确认的改动。

源码同步可能包含草稿和私有内容，建议使用私有源码仓库。“仅本地”文档目录不会参与后续同步，但此前已推送的内容仍可能保留在 Git 历史中。需要 Git 代理时，在“设置 → 基础设置”配置；认证使用本机 Git 凭据环境，不要把口令写进仓库地址。

发布站点

1. 在“设置 → 站点设置”填写“正式网址”；部署到仓库子路径时，再填写“部署子路径”。
2. 在“发布”页右侧的“管理发布目标”中新增目标，并填写目标位置与认证信息。
3. 在左侧“本次发布到”勾选目标。先点“发布检查（不上传）”，确认公开构建和目标配置，再点“正式发布”。
4. 查看“结果与日志”和“发布记录”。完成后打开网站，检查首页、深层文档、图片和内部链接。

可以一次勾选多个目标：BookX 先构建一次公开站点，再按勾选顺序逐个发布。某个目标失败不会撤销已经成功的目标；请分别查看每个目标的结果。发布目录或 Git 分支应专门用于该站点，不要在其中手工维护需要长期保留的其他文件。

SSH 目标支持私钥文件或 SSH Agent。当前版本不会验证服务器主机指纹，配置前请通过可信渠道核对服务器身份。发布后命令只在上传成功后执行；命令失败不会撤销已上传的文件。

GitHub Pages

如果源码仓库中有草稿或私有内容，使用独立的公开仓库保存站点文件。在“管理发布目标”中选择“Git 分支”，填写公开仓库的 HTTPS 地址和 gh-pages 分支；首次发布后，到该仓库的 Settings → Pages 中选择 Deploy from a branch、gh-pages 和 /(root)。发布到项目站点时，在 BookX 的“站点设置”填写站点域名和仓库对应的“部署子路径”。

同一次发布的多个目标共用一套站点地址。如果一个目标部署在根路径、另一个部署在子路径，需要分别调整站点设置并发布。GitHub Pages 分支设置见 GitHub 官方说明。