1. 项目概述与核心价值如果你是一名独立游戏开发者或者在一个小团队里用 Godot 引擎做项目那你肯定对“打包发布”这件事又爱又恨。爱的是看到自己的游戏变成一个可执行文件或网页那种成就感无与伦比恨的是这个过程往往繁琐、重复而且容易出错。尤其是在你需要为 Windows、Linux、macOS、Web 甚至 Android 等多个平台构建版本时手动操作不仅耗时还难以保证每次构建的环境完全一致。更别提你还需要把这些构建好的版本上传到 Itch.io、GitHub Pages 等平台进行分发或测试。今天要聊的abarichello/godot-ci项目就是专门为解决这些痛点而生的。它是一个预配置好的 Docker 镜像结合 GitLab CI 或 GitHub Actions能帮你实现 Godot 项目的全自动化构建、测试与部署也就是我们常说的 CI/CD持续集成/持续部署。简单来说这个工具把构建环境特定版本的 Godot 引擎、导出模板等封装进一个 Docker 容器里。无论你用的是 GitLab 还是 GitHub只需要在项目里放一个配置文件.gitlab-ci.yml或.github/workflows/godot-ci.yml它就能在每次代码推送比如到main分支时自动触发流水线完成游戏的导出并把成品发布到你指定的地方。这意味着你可以把精力完全集中在游戏开发上而将重复的构建发布工作交给机器。对于个人开发者和小团队而言这不仅能提升效率更是迈向专业化工作流的关键一步。接下来我会结合自己多次配置和使用的经验带你彻底拆解这个工具从原理到实操再到避坑指南让你也能轻松搭建起属于自己的自动化游戏发布流水线。2. 核心原理与架构设计解析2.1 为什么选择 Docker CI/CD 的方案在深入godot-ci的具体实现之前我们得先搞清楚它背后的设计逻辑。为什么是 Docker为什么是 CI/CD首先环境一致性是游戏构建中最头疼的问题之一。你的 Godot 项目在你自己电脑的 Windows 上导出正常但到了队友的 macOS 上可能就报错。原因可能千奇百怪Godot 版本号的小数点后一位不同、导出模板没同步、甚至是系统路径的差异。Docker 镜像的核心价值就在于它把一个完整的、可运行的构建环境包括操作系统、Godot 二进制文件、导出模板、必要的依赖库打包成了一个“集装箱”。无论这个集装箱被运到哪台服务器GitLab Runner 或 GitHub Actions 的虚拟机上运行内部环境都是一模一样的。这从根本上杜绝了“在我机器上是好的”这类问题。其次自动化与可重复性。CI/CD 的核心思想是将代码变更自动转化为可交付的产物。对于 Godot 项目这个“产物”就是各个平台的游戏包。通过编写一个声明式的配置文件YAML你定义了从代码到成品的完整流水线。每次推送代码这个流水线就会自动执行无需人工干预。这不仅节省了时间更重要的是它确保了每次构建的过程都是可追溯、可重复的。如果你想回溯三个月前的某个版本只需找到对应的 Git 提交触发流水线就能得到完全一样的构建结果。最后与现有开发流程无缝集成。GitLab 和 GitHub 是现代代码托管和协作的事实标准。godot-ci直接为这两个平台提供了开箱即用的配置模板意味着你不需要搭建复杂的 Jenkins 服务器或自己写一堆脚本。你的代码仓库、版本管理、问题跟踪和自动化构建发布全部在一个生态内完成管理成本极低。2.2godot-ciDocker 镜像剖析barichello/godot-ci这个 Docker 镜像并不是一个简单的 Godot 运行时。它是一个为自动化导出量身定制的工具链集合。以常用的barichello/godot-ci:3.5标签为例我们来看看它里面到底有什么基础操作系统通常基于一个轻量级的 Linux 发行版如 Alpine 或 Debian slim确保镜像体积小启动快。Godot 引擎本体预安装了指定版本如 3.5的 Godot 无头模式headless可执行文件。无头模式意味着没有图形界面完全通过命令行操作这正是自动化脚本所需要的。导出模板包含了对应 Godot 版本的所有标准导出模板Windows、Linux、macOS、Web 等。这些模板是游戏能打包成不同平台可执行文件的关键。辅助工具butlerItch.io 官方的命令行部署工具用于将构建好的游戏包上传到 Itch.io。git用于操作 Git 仓库特别是在部署到 GitHub/GitLab Pages 时需要将生成的网页文件提交到特定分支。curl、wget、unzip等常用工具用于处理可能的下载和解压任务。预设的工作目录与路径镜像内部已经设置好了 Godot 查找导出模板和配置的默认路径如~/.local/share/godot/确保godot --export命令能直接找到所需资源。这个镜像就像一个移动的“构建车间”里面机床Godot、模具导出模板、打包工具butler一应俱全随时可以被 CI 系统调用开工。2.3 CI/CD 流程工作流拆解无论是 GitLab CI 还是 GitHub Actions其工作流都可以概括为以下几个核心阶段我们可以通过一个向 Web 和 Itch.io 发布的例子来理解触发阶段当你向仓库的特定分支如main推送代码或创建合并请求Pull Request时CI 系统会检测到变更。准备阶段CI 系统根据你的配置文件创建一个全新的、干净的环境虚拟机或容器并拉取你的项目代码。构建阶段这是godot-ci的核心。CI 系统启动一个基于barichello/godot-ci:xxx镜像的 Docker 容器。将你的项目代码目录“挂载”到容器内部。在容器内执行你定义的script命令。例如godot --export HTML5 web/index.html godot --export Windows Desktop builds/game.exe这些命令会调用容器内预装的 Godot读取你项目中的export_presets.cfg文件并执行导出操作。产物收集阶段导出命令会在项目目录下生成对应的文件如web/文件夹、builds/game.exe。CI 系统能将这些文件保留为“构建产物”Artifacts供后续步骤使用或提供下载。部署阶段对于 WebGitHub Pages脚本会进入web/目录将其初始化为一个 Git 仓库然后推送到远程仓库的gh-pages分支。GitHub Pages 服务会自动从这个分支提供静态网页服务。对于 Itch.io脚本会调用容器内预装的butler工具将builds/目录下的文件推送到你指定的 Itch.io 游戏页面。butler会自动处理版本比对、增量上传等复杂工作。清理与报告阶段所有步骤完成后CI 系统会清理环境并向你发送成功或失败的通知邮件、站内信等。整个流程完全自动化你只需要提交代码剩下的就交给这个无形的“流水线工人”去完成。3. 实战配置从零搭建自动化流水线理论讲得再多不如亲手配置一遍。下面我将以 GitHub Actions 为例详细演示如何为一个 Godot 3.5 项目配置自动化导出到 GitHub Pages 和 Itch.io 的完整流程。GitLab CI 的配置逻辑几乎完全一致只是语法和变量设置位置稍有不同。3.1 前期准备本地项目配置在配置 CI 之前你的本地 Godot 项目必须做好正确配置这是自动化导出的基础。第一步正确设置导出预设这是最容易出错的一步。在 Godot 编辑器中进入项目 - 导出。点击“添加…”为你的游戏添加目标平台例如“HTML5”和“Windows 桌面版”。对每个预设进行详细配置如 Web 的渲染模式、Windows 的图标等。关键在导出对话框的顶部为每个预设设置一个唯一的、准确的“导出预设名称”。例如我将 Web 平台预设命名为HTML5将 Windows 平台预设命名为Windows Desktop。这个名称区分大小写并且将在 CI 配置文件中被直接引用。点击“导出项目”按钮至少手动导出一次。这会在你的项目根目录下生成一个export_presets.cfg文件。这个文件包含了所有导出配置。重要提示export_presets.cfg文件必须提交到 Git 仓库中。它不应该被添加到.gitignore。因为 CI 构建时依赖的就是这个文件里的配置。但同时这个文件里可能包含敏感信息如 Android 签名密钥的路径所以你需要格外小心。一个最佳实践是在导出预设中不要填写 Android 发布密钥或 Windows 代码签名的具体密码这些敏感信息应该通过 CI 的环境变量在运行时注入。对于本地调试可以使用独立的调试密钥配置。第二步规划项目目录结构一个清晰的结构有助于管理构建产物。我建议在项目根目录下创建以下文件夹或类似结构并在.gitignore中忽略它们因为 CI 会重新生成my_godot_game/ ├── .github/ │ └── workflows/ # GitHub Actions 配置文件将放在这里 ├── addons/ # 插件 ├── scenes/ # 场景文件 ├── scripts/ # 脚本文件 └── (其他 Godot 项目文件)构建产物我们规划输出到项目根目录外的dist/或builds/文件夹但 CI 通常在工作目录内操作所以我们暂时规划输出到项目内的build/目录并在.gitignore中忽略它。3.2 配置 GitHub Actions 工作流在你的 Godot 项目根目录下创建.github/workflows/文件夹然后在里面创建一个 YAML 文件例如deploy.yml。我们将创建一个包含两个任务Job的工作流一个用于构建 Web 版本并部署到 GitHub Pages另一个用于构建桌面版并发布到 Itch.io。name: Build and Deploy Godot Project on: push: branches: [ main ] # 仅在推送到 main 分支时触发 pull_request: branches: [ main ] # 在向 main 分支提 PR 时也触发通常仅构建不部署 jobs: # 任务一构建 Web 版本并部署到 GitHub Pages deploy-web: runs-on: ubuntu-latest # 使用 GitHub 提供的 Ubuntu 虚拟机 container: image: barichello/godot-ci:3.5 # 使用 Godot 3.5 的 CI 镜像 steps: - name: Checkout Repository uses: actions/checkoutv3 with: path: project # 将代码检出到 project/ 子目录方便管理 - name: Setup Export Templates run: | # 将容器内预装的导出模板移动到 Godot 期望的用户目录 mkdir -p ~/.local/share/godot/export_templates mv /root/.local/share/godot/export_templates/3.5.stable ~/.local/share/godot/export_templates/ - name: Export HTML5 Project run: | cd project # 关键命令使用预设名“HTML5”导出输出到上级目录的 web_build 文件夹 godot --export HTML5 ../web_build/index.html shell: bash - name: Deploy to GitHub Pages uses: peaceiris/actions-gh-pagesv3 # 一个专门部署到 gh-pages 的 Action with: github_token: ${{ secrets.GITHUB_TOKEN }} # GitHub 自动提供的令牌 publish_dir: ./web_build # 要部署的目录 # 以下用户信息可选用于配置提交者 user_name: github-actions[bot] user_email: github-actions[bot]users.noreply.github.com # 任务二构建桌面版并发布到 Itch.io deploy-itch: runs-on: ubuntu-latest container: image: barichello/godot-ci:3.5 needs: deploy-web # 表示此任务在 deploy-web 成功后执行非必须可并行 steps: - name: Checkout Repository uses: actions/checkoutv3 with: path: project - name: Setup Export Templates run: | mkdir -p ~/.local/share/godot/export_templates mv /root/.local/share/godot/export_templates/3.5.stable ~/.local/share/godot/export_templates/ - name: Export Windows Project run: | cd project # 创建构建输出目录 mkdir -p ../itch_build # 使用预设名“Windows Desktop”导出 godot --export Windows Desktop ../itch_build/my_game.exe - name: Deploy to Itch.io via Butler run: | # 使用 butler 推送 itch_build 目录下的所有内容 # ITCHIO_USER 和 ITCHIO_GAME 是你在 Itch.io 的用户名和游戏名 butler push ../itch_build ${{ secrets.ITCHIO_USER }}/${{ secrets.ITCHIO_GAME }}:windows --userversion 0.1.${{ github.run_number }} env: BUTLER_API_KEY: ${{ secrets.BUTLER_API_KEY }} # 你的 Itch.io API 密钥配置文件关键点解析container:指定了使用barichello/godot-ci:3.5镜像这确保了构建环境的一致性。Setup Export Templates步骤这是必须的。Docker 镜像将导出模板放在 root 用户目录下但 Godot 在非 root 用户运行时GitHub Actions 默认会去当前用户目录查找。这一步就是把模板移动到正确位置。godot --export命令这是核心导出命令。HTML5和Windows Desktop必须与你项目export_presets.cfg中定义的预设名称完全一致包括大小写和空格。如果名称中有空格必须用引号括起来。GitHub Pages 部署我们使用了社区优秀的peaceiris/actions-gh-pagesAction它简化了向gh-pages分支推送的流程。secrets.GITHUB_TOKEN是 GitHub 自动为工作流提供的无需额外配置。Itch.io 部署我们直接调用镜像内预装的butler命令行工具。butler push命令的格式是butler push 构建目录 itch用户名/游戏名:渠道。这里的:windows是一个渠道标签你可以在 Itch.io 后台管理不同平台的版本。--userversion指定版本号这里我们巧妙地使用了 GitHub Actions 的运行编号${{ github.run_number }}作为版本号的一部分确保每次构建都有唯一版本。3.3 配置敏感信息与仓库密钥在上面的配置中我们引用了几个secrets如secrets.ITCHIO_USER、secrets.ITCHIO_GAME和secrets.BUTLER_API_KEY。这些是敏感信息绝对不能直接写在代码里。在 GitHub 仓库中设置 Secrets进入你的 GitHub 仓库页面。点击Settings-Secrets and variables-Actions。点击New repository secret。ITCHIO_USER: 你的 Itch.io 用户名。ITCHIO_GAME: 你在 Itch.io 上创建的游戏项目名称slug。BUTLER_API_KEY: 在 Itch.io 的 API 密钥设置页面 生成一个密钥。设置完成后这些密钥会以加密形式存储并在工作流运行时被注入到环境变量中从而被${{ secrets.XXX }}引用。对于 GitLab CI流程类似你需要进入项目的Settings - CI/CD - Variables来添加变量。注意GitLab 的变量有“保护”和“掩码”选项对于 API 密钥务必勾选“掩码”Masked防止其在日志中意外输出。3.4 针对 MonoC#项目的特殊配置如果你的 Godot 项目使用了 C#你需要使用 Mono 版本的镜像和导出模板。修改镜像标签在 YAML 文件的container.image部分将barichello/godot-ci:3.5替换为barichello/godot-ci:mono-3.5。修改导出模板路径在Setup Export Templates步骤中模板路径需要从3.5.stable改为3.5.stable.mono。- name: Setup Export Templates (Mono) run: | mkdir -p ~/.local/share/godot/export_templates mv /root/.local/share/godot/export_templates/3.5.stable.mono ~/.local/share/godot/export_templates/注意你需要移动的是.mono目录并且 Godot Mono 版本在导出时会自动查找带有.mono后缀的模板路径。有时你可能需要将移动后的文件夹重命名为 Godot 期望的格式但godot-ci镜像通常已做好适配按上述操作即可。4. 高级用法、优化与故障排查4.1 多平台并行构建优化上面的示例中两个任务是顺序执行的。为了提高效率我们可以让它们并行执行只要它们之间没有依赖关系。只需移除deploy-itch任务中的needs: deploy-web这一行两个任务就会同时开始。jobs: deploy-web: runs-on: ubuntu-latest # ... 步骤同上 deploy-itch: runs-on: ubuntu-latest # 移除 needs 配置使其与 deploy-web 并行 # ... 步骤同上更进一步你可以在一个任务内使用strategy.matrix来为多个平台如 Windows, Linux, macOS动态创建并行的构建任务这对于大型项目非常有用。4.2 处理自定义模块与引擎编译有时你的项目依赖第三方 Godot 模块如 GDNative 的 C 绑定或自定义编译的引擎。godot-ci的基础镜像不包含这些。你需要一个两阶段流程编译阶段使用一个专门用于编译 Godot 引擎含自定义模块的 CI 任务。可以参考 Calinou/godot-builds-ci 这样的项目它提供了自动化编译 Godot 的 CI 配置。这个任务会产出一个自定义的 Godot 可执行文件。导出阶段将上一步编译好的 Godot 可执行文件作为构建产物Artifact保存下来。在godot-ci任务中不是使用预制的 Docker 镜像而是使用一个基础 Linux 镜像然后手动下载你编译好的 Godot 二进制文件并设置好导出模板路径再进行导出操作。这属于高级用法需要对 CI 的产物传递和自定义脚本有更深的理解。核心思路是将“构建 Godot 引擎”和“使用 Godot 导出游戏”拆分成两个独立的、可复用的 CI 阶段。4.3 常见问题与排查技巧实录即使配置看起来完美第一次运行时也难免遇到问题。下面是我踩过的一些坑和解决方法问题一导出失败Godot 报错找不到导出预设或资源。检查点 1export_presets.cfg文件。确保它已提交到仓库并且没有被.gitignore排除。可以通过在 CI 日志中添加ls -la命令来确认文件是否存在。检查点 2导出预设名称。确认 CI 配置文件中godot --export命令后的预设名称字符串与export_presets.cfg文件中的name字段完全一致。一个常见的错误是在 Godot 编辑器中看到的列表名称和实际配置的名称可能不同。最好直接打开export_presets.cfg文件搜索name来确认。检查点 3相对路径。Godot 导出时使用的是项目目录的相对路径。确保 CI 的run步骤中执行godot命令的当前工作目录是你的项目根目录。这就是为什么我们在示例中先执行了cd project。问题二Butler 上传到 Itch.io 失败提示认证错误。检查点 1API 密钥。确认BUTLER_API_KEY这个 Secret 设置正确且没有多余的空格。可以尝试在本地安装 Butler用同样的密钥测试butler login命令以验证密钥本身有效。检查点 2游戏标识。确认ITCHIO_USER和ITCHIO_GAME的组合是否正确。ITCHIO_GAME应该是你游戏页面的“slug”网址的一部分而不是显示名称。例如如果你的游戏页面是https://myusername.itch.io/my-cool-game那么ITCHIO_GAME就是my-cool-game。检查点 3GitLab 变量保护如果是 GitLab CI。如果变量被标记为“Protected”受保护的而你的 CI 流水线运行在非保护分支如特性分支上则该变量不会被注入。确保变量设置与分支策略匹配或暂时取消变量的“Protected”标记进行测试。问题三构建成功但 GitHub Pages 页面空白或显示错误。检查点 1HTML5 导出设置。在 Godot 编辑器中检查 HTML5 导出预设。确保“渲染模式”选择的是“兼容性”Compatibility而非“向前兼容”Forward Compatible后者需要 WebGL 2兼容性较差。也可以尝试勾选“实验性虚拟键盘”等选项。检查点 2文件服务配置。GitHub Pages 是一个静态文件服务器。确保导出的index.html文件及其引用的.pck、.wasm、.js文件都在同一个目录下我们示例中的web_build/并且index.html中加载这些文件的路径是相对路径。godot-ci的导出默认会处理好这些。检查点 3访问控制台。在浏览器中打开部署好的页面按 F12 打开开发者工具查看“控制台”Console和“网络”Network标签页这里通常会有具体的错误信息。问题四CI 流水线运行缓慢。优化点 1缓存 Docker 镜像。GitHub Actions 和 GitLab CI 都支持缓存。你可以配置缓存 Docker 镜像层避免每次运行都从头拉取整个镜像。对于 GitHub Actions可以使用actions/cache配合特定键值来实现。优化点 2缓存 Godot 导出模板。虽然godot-ci镜像内置了模板但每次移动模板也需要时间。如果使用自定义或更新频繁的模板可以考虑将其下载并缓存到 CI 的工作空间。优化点 3只构建变更的平台。通过分析代码变更可以设计更智能的流水线例如只有修改了平台相关代码时才构建该平台。但这需要更复杂的脚本逻辑。一个实用的调试技巧在 CI 脚本中增加调试信息。在关键的步骤前后添加一些echo命令来打印当前目录、环境变量或文件列表。- name: Debug Info run: | pwd ls -la echo Preset name is: HTML5 # 检查导出模板 ls -la ~/.local/share/godot/export_templates/这些日志会在 CI 的运行详情中输出是定位问题最直接的手段。5. 安全最佳实践与扩展思路5.1 安全注意事项保护你的密钥自动化带来了便利也带来了风险。一旦 API 密钥或代码签名证书泄露后果可能很严重。永远不要将密钥硬编码在配置文件或代码中。务必使用 CI 系统提供的 Secrets/ Variables 功能。最小化权限原则为 Butler 创建的 Itch.io API 密钥只赋予它必要的权限通常只需要上传游戏的能力。定期轮换更新这些密钥。小心export_presets.cfg这个文件是纯文本。如果你在其中配置了 Android 的发布密钥库keystore路径和密码那么这些信息也会被提交到代码仓库。绝对不要这样做。正确做法是在export_presets.cfg中为 Android 发布预设使用一个占位符路径如release.keystore和空密码。在 CI 脚本中通过环境变量或 Secrets 获取真实的密钥库文件可以 Base64 编码后存为变量、别名和密码。在构建步骤中动态创建这个密钥库文件并在godot --export命令中通过--export-pack或修改临时配置文件的方式将正确的路径和密码传递给 Godot。godot-ci的模板中通常包含了处理 Android 密钥的示例脚本请仔细参考。5.2 扩展工作流测试、版本管理与更多平台基本的构建部署流水线搭建好后你可以考虑将其扩展得更专业。集成自动化测试在导出之前可以增加一个测试阶段。Godot 支持通过命令行运行 GDScript 或 C# 的单元测试。你可以编写针对核心游戏逻辑的测试并在 CI 中运行确保新提交的代码不会破坏现有功能。- name: Run Unit Tests run: | cd project godot --script res://tests/runner.gd # 假设你有一个测试运行器脚本自动化版本号管理手动更新游戏版本号很容易忘记。你可以让 CI 根据 Git 标签Tag或提交历史自动生成版本号并注入到游戏代码中例如通过修改一个version.gd脚本文件或使用--export的参数。发布到更多平台除了 Itch.io 和 GitHub Pages你还可以扩展流水线将构建产物发布到 Steam通过 Steamworks SDK 命令行、GOG 或甚至游戏主机开发门户这需要特定的 SDK 和授权。思路都是类似的在 CI 中集成对应平台的命令行工具并在构建成功后调用它们进行上传。构建状态徽章GitHub Actions 和 GitLab CI 都提供了构建状态徽章Badge的 Markdown 代码。你可以将其添加到项目的README.md中直观地展示当前主分支的构建状态是成功还是失败这显得非常专业。经过以上步骤你应该已经能够将一个零散的 Godot 项目转变为一个拥有自动化构建、测试和部署能力的“现代化”项目。abarichello/godot-ci这个工具链极大地降低了 CI/CD 的入门门槛。刚开始配置时可能会遇到一些障碍但一旦跑通它为你节省的时间和带来的安心感是巨大的。记住好的工具不是为了增加复杂度而是为了让你更专注于创造本身——也就是你的游戏。