Quarto项目渲染输出文件夹的Robocopy镜像同步

避免file.copy简单复制形成残留文件，同时保留上传工具Resilio Sync的状态文件夹

Author

huhuaping

Published

May 15, 2026

本目录是一套可整体复制到其他 Windows + Quarto Book 项目的脚本与配置模板：Robocopy /MIR 将渲染输出同步到 staging，并用 /XD 保留上传工具状态目录（默认排除 .sync）。设计说明、环境变量与注意事项见 docs/quarto-book-robocopy-mirror.qmd。

目录内容

文件	用途
`copy-post-sync.R`	供 `_quarto.yml` 的 `project.post-render` 调用；读项目根 `.Renviron`（若存在），校验路径后执行 `robocopy`；成功退出码 ≤7。
`mirror-book-sync.ps1`	不跑完整 render 时，在命令行单独执行同一镜像逻辑；支持 `-From` / `-To` 覆盖环境变量。
`_quarto.post-render.snippet.yml`	供合并进业务书 `_quarto.yml` 的 `post-render` 片段（Install-Harness 会复制为 `_quarto.harness-post-render.yml`）。
`.Renviron.example`	本机示例（含绝对路径时请勿提交仓库）；正式项目应复制为根目录 `.Renviron` 并加入 `.gitignore`，或参考仓库根部的 `.Renviron.example`。

从 harness 安装到书项目（推荐）

在 harness 仓库根：

.\scripts\powershell\Install-Harness.ps1 -InstallProfile quarto-sync -ProjectRoot "D:\path\to\your-book"

参数与 profile 说明见 docs/install-harness.qmd。仍支持手动复制下列「最小步骤」。

将整个 quarto-sync 文件夹放到 Quarto 项目根目录下（与 _book、_quarto.yml 同级），使 mirror-book-sync.ps1 内默认的相对路径 _book、_book_sync 相对于项目根解析（脚本以「本文件夹的上一级目录」为根）。本 harness 仓库中该目录在 scripts/quarto-sync/，此时上一级为 scripts/，单独跑 PS1 时请依赖 .Renviron 中的绝对路径或 -From/-To。
在 _quarto.yml 中增加 post-render，路径与拷贝位置一致，例如根目录包：quarto-sync/copy-post-sync.R；若仍放在 scripts/quarto-sync/，则为 scripts/quarto-sync/copy-post-sync.R。
确保项目依赖 R 包 here（copy-post-sync.R 使用 here::here()）。
在项目根维护 .Renviron，设置 BOOK_MIRROR_FROM、BOOK_MIRROR_TO、BOOK_MIRROR_EXCLUDE_DIRS（可选）；跨项目镜像时使用绝对路径或先设置进程环境变量再执行 quarto render / PS1。

使用方法1：quarto render 直接调用R脚本

在quarto 项目中：（1）设定.Renviron文件，设定参数（文件夹路径）BOOK_MIRROR_FROM（源文件夹路径）、BOOK_MIRROR_TO（目标文件夹路径）、BOOK_MIRROR_EXCLUDE_DIRS（排除目录，可选）。（2）设定_quarto.yml中的post-render，使其调用R脚本copy-post-sync.R。（3）针对quarto项目，完成render后，quarto会自动调用R脚本，将渲染输出文件夹_book/同步镜像到文件夹_book_sync/。

project:
  type: book
  output-dir: _book
  post-render:
    - scripts/quarto-sync/copy-post-sync.R

# .Renviron
BOOK_MIRROR_FROM=D:/github/books-quarto/_book
BOOK_MIRROR_TO=D:/github/books-quarto/_book_sync
BOOK_MIRROR_EXCLUDE_DIRS=.sync,.rclone-cache

使用方法2：执行powershell脚本

在quarto 项目中，注释掉_quarto.yml中的post-render，避免quarto render 直接调用R脚本（copy-post-sync.R）。先完成项目的整体render后，检查生成的_book文件夹。确认无误后，可以执行powershell脚本，将渲染输出文件夹_book/同步镜像到文件夹_book_sync/。如果需要跨项目镜像，可以设置环境变量或使用参数-From和-To。

# 项目根（与 _quarto.yml 同级）；若脚本在 scripts/quarto-sync/，请改写路径
powershell -File quarto-sync/mirror-book-sync.ps1
# 或显式路径
.\quarto-sync\mirror-book-sync.ps1 -From "D:\repoA\_book" -To "D:\repoB\_book_sync"

详细约定（退出码、路径安全、排除目录回退规则等）以主文档与脚本内注释为准。