首页 技术

根据我们现有的游戏规模以及开发需求，传统的 “本地 Build 后再手动上传到云端” 的做法显得相对繁琐。尤其在多人协作以及多设备切换的场景下，手动部署为代码的快速迭代设下了阻碍。作为追求极致效率的开发者，我们必须把这种低价值的重复劳动交给机器。这样不仅便于随时随地访问测试，也无须每次都登录腾讯云手动替换网页文件。

本文将记录如何利用 GitHub Actions 结合 腾讯云 COS（对象存储），为 Unity 项目打造一套 “推代码即上线” 的 CI/CD 工具链。

# 1. 架构逻辑：云端 “数字工厂” 的流水线

这套自动化方案的核心逻辑在于：将本地的开发环境与云端的生产环境彻底解耦。GitHub Actions 充当了 “虚拟实验室”，它会在我们每次执行 git push 时自动触发以下生命周期：

  1. 环境克隆： 拉取 GitHub 上的代码仓库及 LFS 大文件。
  2. 云端激活： 抛弃传统的本地证书，利用 Unity 账号与序列号（Serial）在云端即时获取 Pro/Student 授权。
  3. 编译构建： 调用官方定制化 Docker 镜像，将 C# 翻译并极限压缩输出 WebGL 产物。
  4. 远程同步： 调用腾讯云官方底层命令，将 Build 产物精准推送到 COS 存储桶。

# 2. 配置文件：.github/workflows/deploy.yml

这是自动化流程的源码。需要注意的是，我们采用了账号密码 + 序列号在线激活的方式，彻底避开了现代 Unity 极其苛刻的设备绑定检测。同时，我们使用了腾讯云官方的 Python CLI 工具来代替容易报错的第三方插件。

name: 🚀 Unity WebGL Auto Deploy
on:
  push:
    branches: [ main ] # 监听主分支，一推代码即刻发动
jobs:
  build_and_deploy:
    name: 🏗️ WebGL Build & Sync
    runs-on: ubuntu-latest
    steps:
      # 1. 把仓库代码搬到云端服务器
      - name: Checkout Repository
        uses: actions/checkout@v4
        with:
          lfs: true
      # 2. 缓存 Library：将二次打包时间从 20min 压缩至 5min 的关键护城河
      - name: Cache Assets
        uses: actions/cache@v3
        with:
          path: Library
          key: Library-WebGL-$<!--swig0-->
      # 3. 核心：调用云端 Unity 在线直连激活并进行 WebGL 炼金
      - name: Build WebGL
        uses: game-ci/unity-builder@v4
        env:
          UNITY_EMAIL: $<!--swig1-->
          UNITY_PASSWORD: $
          UNITY_SERIAL: $ # 使用序列号直接向官方服务器申请通行证
        with:
          targetPlatform: WebGL
          unityVersion: 2020.3.47f1 # 注意：这里必须是国际版后缀 f1，不能带 c1
      # 4. 放弃老旧的 JS 插件，安装 Python 环境
      - name: Setup Python environment
        uses: actions/setup-python@v4
        with:
          python-version: '3.x'
          
      # 5. 调用腾讯云官方 coscmd 工具进行暴力部署
      - name: Sync to Tencent Cloud via COSCMD 🚀
        env:
          SECRET_ID: $<!--swig4-->
          SECRET_KEY: $
          COS_BUCKET: $
          COS_REGION: $
        run: |
          pip install coscmd
          coscmd config -a $SECRET_ID -s $SECRET_KEY -b $COS_BUCKET -r $COS_REGION
          # 将打包出的 WebGL 文件夹全量同步到线上访问路径
          coscmd upload -r build/WebGL/WebGL/ /privacy/
# 3. 实战避坑指南 (Troubleshooting)


在配置这条流水线的过程中，云端极度的环境会无限放大本地开发时被忽略的细节。以下是几个实战遇到的问题


# 坑一：中国特供版版本号


    

  • 症状： GitHub Actions 提示找不到对应的 Docker 镜像（如  2020.3.47f1c1 ）。
    • 

  • 原因： 中国区特供的增强版 Unity 版本号往往带有  c1  后缀，而 GitHub Actions 的 Game-CI 镜像库只认国际版的标准后缀。
    • 

  • 解法： 在 YAML 配置文件中，强行将  unityVersion  的后缀抹除，改为  2020.3.47f1  即可完美兼容。
    • 



# 坑二：授权许可证不再签发了


    

  • 症状： 手动上传  .ulf  许可证文件后，云端始终报  Invalid license  或  MachineID  不匹配。
    • 

  • 原因： 现代 Unity Hub 生成的离线证书往往是绑定了本地硬件信息的 “锁机版”（带有  <MachineBindings> ）。云端每次初始化的虚拟机硬件不同，导致验证必败。
    • 

  • 解法： 彻底抛弃文件激活方案。直接在 GitHub Secrets 中配置  UNITY_SERIAL （Pro/Student 序列号），让云端容器在打包前联网暴破直连激活，用完自动释放。
    • 



# 坑三：幽灵依赖作祟 ——  autostreaming  报错


    

  • 症状：  Package Manager  阶段突然报错： com.unity.modules.autostreaming cannot be found 。
    • 

  • 原因： 在 2020 等特定版本的 Unity 中，工程初始化时可能会默认写入  autostreaming  依赖包。由于官方早已废弃该模块，本地环境有历史缓存不会报错，但在纯净无缓存的 Linux CI 容器拉取时，会导致整条构建链条崩溃。
    • 

  • 解法： 进入本地项目的  Packages/manifest.json  文件，找到  "com.unity.modules.autostreaming"  这一行，连带末尾的逗号一起物理删除，重新 Push 即可。
    • 



# 坑四：部署上传插件的  [object Object]  谜团


    

  • 症状： 打包全部成功，但在最后一步上传腾讯云 COS 时报错  fail to upload files to cos: [object Object] 。
    • 

  • 原因： 很多旧教程推荐使用的  TencentCloud/cos-action@v1  第三方 JavaScript 插件年久失修，对最新的 Node.js 环境水土不服，无法正常抛出错误信息。
    • 

  • 解法： 直接在 YAML 中配置  actions/setup-python ，并使用腾讯云官方底层命令行工具  coscmd  替代旧插件（参考上文配置）。官方工具不仅速度极快，报错也会给出精确的大白话。
    • 



# 坑五：上线后的 “最后一公里” —— CORS 跨域拦截


    

  • 症状： 游戏在网页上成功加载，但在向腾讯云开发（TCB）或云数据库发送请求时，按 F12 会看到红色的  CORS policy: No 'Access-Control-Allow-Origin' header  拦截报错。
    • 

  • 原因： 浏览器强制的安全策略。当游戏从你的专属域名发请求给腾讯云服务器时，如果没有提前报备，就会被当成跨域攻击拦截。
    • 

  • 解法： 登录腾讯云开发控制台 -> 环境设置 -> 安全设置，在 **“WEB 安全域名”** 中，添加你的游戏访问域名（如  game.homura.cn  或  *.homura.cn ），等待一分钟生效即可通关全流程。
    •