Zola 静态网站部署到 Sourcehut Pages基于 .build.yml 的自动化构建与发布完整指南【免费下载链接】zolaA fast static site generator in a single binary with everything built-in. https://www.getzola.org项目地址: https://gitcode.com/GitHub_Trending/zo/zolaSourcehut Pages 是 Sourcehut 生态内提供的静态站点托管服务支持通过 build.sr.ht 的 CI 构建流水线自动拉取源码、执行构建并发布产物。Zola 构建出的纯静态文件无需数据库与后端服务与这种“推送即部署”的工作流天然契合。读完本文你将掌握为 Zola 项目编写.build.yml构建清单、使用hut pages publish上传产物、以及配置自定义域名的完整流程并能在源码层面理解zola build的输出行为。部署前置条件开始之前需要准备好两样东西一个 Zola 项目项目的根目录包含config.toml或zola.toml以及content/、templates/、static/等标准目录结构可以使用zola init快速创建一个 Sourcehut 仓库将项目推送到 Sourcehut 的 git 或 hg 仓库用于后续的构建与版本管理。Sourcehut Pages 本身是只读托管服务所有构建与发布动作都由 build.sr.ht 的 CI 在云端完成因此部署的核心工作就是在项目根目录编写一个名为.build.yml的构建清单文件。部署机制一切由 .build.yml 驱动Zola 站点的部署不需要 SSH 登录服务器、也不需要手动上传文件Sourcehut 会为每次git push自动触发一次构建任务。构建任务的行为完全由项目根目录的.build.yml清单定义它描述了构建环境基础镜像、需要预装的软件包需要的权限本例中为 Pages 的读写令牌环境变量目标域名源码来源你的仓库地址依次执行的任务构建、打包、上传。编写 .build.yml 构建清单官方推荐的模板可以在 Sourcehut 的 pages.sr.ht-examples 示例仓库中找到也可以直接使用下面这份完整清单它是 Sourcehut Pages 官方 Zola 部署方案的完整示例image: alpine/edge packages: - hut - zola oauth: pages.sr.ht/PAGES:RW environment: site: your_username.srht.site sources: - https://git.sr.ht/~your_username/my-website tasks: - build: | cd my-website zola build - package: | cd my-website tar -C public -cvz . ../site.tar.gz - upload: | hut pages publish -d $site site.tar.gz各字段逐项说明字段作用本示例取值image构建环境的基础镜像alpine/edgeAlpine 边缘版本足够轻量packages构建环境中预装的软件包hutSourcehut 官方命令行工具、zola本项目的静态站点生成器oauth构建任务申请的 OAuth 授权pages.sr.ht/PAGES:RW授予 Pages 服务的读写权限environment注入任务执行时的环境变量site保存目标域名后续上传任务通过$site引用sources构建任务要克隆的源码仓库地址https://git.sr.ht/~your_username/my-website仓库名my-website会被克隆为同名目录tasks按顺序执行的构建步骤见下文“三步任务流水线”三步任务流水线清单中的tasks定义了三个依次执行的步骤build构建进入克隆下来的my-website目录执行zola build。Zola 会读取配置、渲染全部页面与模板并将生成的静态文件输出到public目录可通过--output-dir参数覆盖详见下文package打包进入my-website目录用tar将public目录整体压缩为site.tar.gztar -C public -cvz . ../site.tar.gz-C public表示先切换到public目录再打包保证压缩包顶层内容就是站点根文件upload上传调用hut pages publish -d $site site.tar.gz把压缩包发布到$site环境变量指定的域名上。hut会自动生成并处理认证令牌你不需要额外配置任何密钥或凭证。整个清单的作用链路很清晰克隆源码 → 构建站点 → 打包产物 → 上传到指定域名全程自动化。从源码理解 zola build 与 public 输出目录要在 Sourcehut 的构建环境中正确打包理解 Zola 的构建输出行为很关键。zola build的实现位于 src/cmd/build.rs它先加载站点Site::new处理可选的--output-dir、--base-url、--drafts、--minify参数最后调用site.build()完成渲染并写入磁盘。关于输出目录有两个值得注意的事实默认输出目录是public在 config 模块 中output_dir的默认值被定义为public并有对应的单元测试default_output_dir与can_add_output_dir验证默认值与自定义覆盖行为可用--output-dir覆盖在 cli.rs 中build子命令提供-o, --output-dir参数注释明确说明默认输出为项目根目录下的public目录当目标目录已存在时会提示是否覆盖配合--force可跳过提示。因此在.build.yml的package步骤中对public目录打包正是基于这一默认约定。如果你的config.toml中修改了output_dir请同步调整打包路径。另外配置中的base_url是唯一必填项详见 configuration 文档。部署前应确认config.toml中的base_url与最终访问域名一致也可以在 CI 中通过zola build --base-url $DEPLOY_URL动态覆盖该参数的完整用法可参考 CLI usage 文档。提交推送触发云端构建.build.yml编写完成后提交并推送到 Sourcehut 仓库即可触发构建$ git push Enumerating objects: 5, done. ... remote: Build started: remote: https://builds.sr.ht/~your_username/job/430625 [.build.yml] To git.sr.ht:~your_username/www fbe9afa..59ae556 master - master推送成功后Sourcehut 会自动启动构建任务。注意输出中的关键信息Sourcehut 会在推送响应里直接返回构建页面的链接如https://builds.sr.ht/~your_username/job/430625你可以打开该页面实时查看每个任务步骤的执行进度与成功状态如果某个步骤失败日志会指出具体出错位置。域名配置默认子域名与自定义域名构建与上传完成后站点即可通过域名访问默认子域名Sourcehut Pages 为每个用户提供your_username.srht.site形式的免费子域名只需在.build.yml的site环境变量中填写该域名即可直接使用自定义域名如果希望使用自己的域名例如blog.mydomain.org需要为该域名配置 DNS 记录使其指向 Sourcehut 的服务器具体记录类型与值请参照 Sourcehut Pages 官方文档中关于自定义域名的说明。部署前的预检与优化建议为了让 Sourcehut 的每次构建更稳定、更省时可以参考以下做法先本地验证构建推送前在本地执行zola build或zola check确认渲染无错误。check子命令会完整构建站点但不写入磁盘并额外检查 Markdown 中的外部链接可用--skip-external-links跳过详见 CLI usage 文档统一 base_url确保config.toml中的base_url与site环境变量指向的域名一致避免生成页面内的链接指向错误域名按需调整输出目录若项目配置了非默认的output_dir记得同步修改package任务中的tar路径善用环境变量environment字段可扩展注入更多变量如构建版本号、语言配置等供多个任务共享使用。至此一个“推送即部署”的 Zola 站点流水线便完成了每次向 Sourcehut 仓库推送代码build.sr.ht 都会自动拉取最新源码、执行zola build生成静态站点、打包public目录并发布到你的域名上全程无需手动干预。【免费下载链接】zolaA fast static site generator in a single binary with everything built-in. https://www.getzola.org项目地址: https://gitcode.com/GitHub_Trending/zo/zola创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考