跳至主要內容

15. 灰度发布和更新

EVOCOSMOS2026/4/13大约 11 分钟

灰度发布和更新

你的游戏上线了，玩家在玩，一切正常。但你发现了一个 bug，或者想加一个新功能。这时候你需要更新游戏。

直接把新版本推给所有玩家？如果新版本有严重 bug，所有人都会受影响。这就是为什么需要灰度发布——先给一小部分人更新，确认没问题后再推给所有人。

什么是灰度发布

打个比方：你开了一家餐厅，研发了一道新菜。你不会直接把所有老顾客的菜都换成新菜——万一新菜不好吃，所有顾客都会不满意。

正确的做法是：先让几张桌的顾客试吃新菜，如果他们说好，再逐步推广到更多桌。

灰度发布（Grayscale Release）就是这个思路：

阶段覆盖范围目的
内部测试开发团队发现明显问题
小范围灰度1%-5% 的玩家验证基本功能
中范围灰度10%-30% 的玩家验证性能和稳定性
全量发布100% 的玩家正式上线

叫法说明

灰度发布在不同地方有不同的叫法：

  • 灰度发布 / 灰度更新（中国互联网常用）
  • 金丝雀发布（Canary Release，国际通用）
  • 分阶段发布（Phased Rollout）
  • 渐进式发布（Progressive Rollout）

说的都是同一件事：不要一次把更新推给所有人。

为什么要灰度发布

真实案例

事故原因后果
某游戏更新后无法登录新版本的服务端接口与旧客户端不兼容几十万玩家无法进入游戏
某游戏更新后存档丢失新版本的存档格式变了，没做数据迁移大量玩家流失
某游戏更新后严重卡顿新功能有内存泄漏玩家疯狂差评

如果这些更新先在 5% 的玩家上灰度测试，问题就会在小范围内被发现和修复，不会影响所有玩家。

灰度发布的实现

版本管理

首先要建立清晰的版本号体系：

主版本号.次版本号.修订号

例如：1.2.3
- 1 = 主版本号（重大更新，可能不兼容旧版本）
- 2 = 次版本号（新增功能，向下兼容）
- 3 = 修订号（Bug 修复，完全兼容）
版本变更示例说明
新增功能1.0.0 → 1.1.0加了新活动系统
修复 Bug1.1.0 → 1.1.1修了活动奖励不发放的问题
重大更新1.1.1 → 2.0.0重做了整个 UI 系统

客户端版本检查

游戏启动时，客户端应该检查是否有新版本：

C
// 版本检查管理器
using Godot;

public partial class VersionManager : Node
{
    // 当前客户端版本
    private const string CurrentVersion = "1.2.0";

    // 最低兼容版本（低于此版本强制更新）
    private const string MinCompatibleVersion = "1.0.0";

    public override void _Ready()
    {
        CheckForUpdate();
    }

    public async void CheckForUpdate()
    {
        GD.Print($"当前版本：{CurrentVersion}");

        // 向服务器请求最新版本信息
        var http = new HttpRequest();
        AddChild(http);

        string url = $"https://api.yourgame.com/version/check?current={CurrentVersion}";
        http.RequestCompleted += OnVersionCheckCompleted;
        http.Request(url);
    }

    private void OnVersionCheckCompleted(long result, long code, string[] headers, byte[] body)
    {
        if (result != (long)HttpRequest.Result.Success)
        {
            GD.PrintErr("版本检查失败，使用当前版本");
            return;
        }

        string json = System.Text.Encoding.UTF8.GetString(body);
        // 解析响应
        // 假设响应格式：
        // {
        //   "latest_version": "1.3.0",
        //   "min_version": "1.1.0",
        //   "download_url": "https://...",
        //   "update_notes": "修复了若干问题",
        //   "force_update": false,
        //   "gray_scale": { "enabled": true, "percentage": 10 }
        // }

        GD.Print($"服务器响应：{json}");
        // 根据响应决定是否提示更新
    }

    // 比较版本号
    public static int CompareVersions(string v1, string v2)
    {
        var parts1 = v1.Split('.');
        var parts2 = v2.Split('.');
        for (int i = 0; i < 3; i++)
        {
            int n1 = int.Parse(parts1[i]);
            int n2 = int.Parse(parts2[i]);
            if (n1 != n2) return n1.CompareTo(n2);
        }
        return 0;
    }
}

灰度策略——服务端决定谁能更新

灰度的核心逻辑在服务端。服务端根据玩家的特征决定他是否在灰度范围内：

// 服务器返回的版本检查响应
{
    "latest_version": "1.3.0",
    "min_version": "1.1.0",
    "download_url": "https://download.yourgame.com/v1.3.0",
    "update_notes": "1. 新增春节活动\n2. 修复了战斗同步问题\n3. 优化了加载速度",
    "update_required": false,
    "gray_scale": {
        "enabled": true,
        "strategy": "user_id_hash",
        "percentage": 10
    }
}
灰度策略说明适用场景
用户 ID 哈希对玩家 ID 取哈希，决定是否在灰度范围最常用，保证同一玩家每次结果一致
白名单指定特定的玩家 ID 列表内测玩家
随机每次请求随机决定不推荐，同一玩家可能时新时旧
按地区特定地区的玩家先更新分区域发布
按设备特定设备型号先更新适配测试

客户端处理更新策略

C
// 更新策略处理
using Godot;

public partial class UpdateHandler : Node
{
    public enum UpdateType
    {
        None,           // 无需更新
        Optional,       // 可选更新
        Required,       // 强制更新
        GrayScale       // 灰度更新
    }

    // 根据服务器响应决定更新策略
    public UpdateType DetermineUpdateAction(
        string currentVersion,
        string minVersion,
        string latestVersion,
        bool isInGrayScale)
    {
        // 当前版本低于最低兼容版本 → 强制更新
        if (VersionManager.CompareVersions(currentVersion, minVersion) < 0)
        {
            GD.PrintErr($"当前版本 {currentVersion} 低于最低兼容版本 {minVersion}，强制更新");
            return UpdateType.Required;
        }

        // 当前版本是最新的 → 无需更新
        if (VersionManager.CompareVersions(currentVersion, latestVersion) >= 0)
        {
            GD.Print("当前已是最新版本");
            return UpdateType.None;
        }

        // 在灰度范围内 → 可更新
        if (isInGrayScale)
        {
            GD.Print("在灰度范围内，可以更新");
            return UpdateType.GrayScale;
        }

        // 不在灰度范围内 → 暂不更新
        GD.Print("不在灰度范围内，等待全量发布");
        return UpdateType.Optional;
    }

    // 显示更新对话框
    public void ShowUpdateDialog(UpdateType type, string notes, string downloadUrl)
    {
        var dialog = new AcceptDialog();
        AddChild(dialog);

        switch (type)
        {
            case UpdateType.Required:
                dialog.Title = "必须更新";
                dialog.DialogText = $"游戏需要更新才能继续运行。\n\n更新内容：\n{notes}";
                dialog.Confirmed += () => OS.ShellOpen(downloadUrl);
                GetTree().Paused = true;
                break;

            case UpdateType.GrayScale:
            case UpdateType.Optional:
                dialog.Title = "发现新版本";
                dialog.DialogText = $"有新版本可用，是否更新？\n\n更新内容：\n{notes}";
                dialog.Confirmed += () => OS.ShellOpen(downloadUrl);
                dialog.Canceled += () => dialog.QueueFree();
                break;
        }

        dialog.PopupCentered();
    }
}

热更新——不重新下载整个游戏

对于 Web 版游戏，每次更新都让玩家重新下载整个包体是不现实的（可能几十上百 MB）。热更新（Hot Update）允许只下载变化的部分。

Godot 的热更新方案

Godot 4 支持在运行时加载 .pck 文件（资源包）。你可以把新版本的资源打包成补丁 PCK，让玩家只下载这个补丁：

C
// 热更新管理器
using Godot;

public partial class HotUpdateManager : Node
{
    // 补丁版本列表（从服务器获取）
    private Godot.Collections.Array<Godot.Collections.Dictionary> _patches;

    // 检查并下载补丁
    public async void CheckAndDownloadPatches()
    {
        // 1. 获取补丁列表
        var patchList = await FetchPatchList();
        if (patchList == null) return;

        // 2. 过滤出需要下载的补丁
        var pendingPatches = FilterPendingPatches(patchList);
        if (pendingPatches.Count == 0)
        {
            GD.Print("没有需要下载的补丁");
            return;
        }

        // 3. 逐个下载并加载
        foreach (var patch in pendingPatches)
        {
            string patchUrl = (string)patch["download_url"];
            string patchVersion = (string)patch["version"];

            GD.Print($"正在下载补丁 {patchVersion}...");
            bool success = await DownloadPatch(patchUrl, $"user://patch_{patchVersion}.pck");
            if (!success)
            {
                GD.PrintErr($"补丁 {patchVersion} 下载失败");
                continue;
            }

            GD.Print($"正在加载补丁 {patchVersion}...");
            LoadPatch($"user://patch_{patchVersion}.pck");
            SaveAppliedPatchVersion(patchVersion);
        }

        GD.Print("所有补丁已加载，建议重启游戏");
    }

    private bool LoadPatch(string path)
    {
        // 加载 PCK 补丁包，它会覆盖已有的同名资源
        bool success = ProjectSettings.LoadResourcePack(path);
        if (success)
        {
            GD.Print($"补丁 {path} 加载成功");
        }
        else
        {
            GD.PrintErr($"补丁 {path} 加载失败");
        }
        return success;
    }

    private async System.Threading.Tasks.Task<bool> DownloadPatch(string url, string savePath)
    {
        var http = new HttpRequest();
        AddChild(http);

        var tcs = new System.Threading.Tasks.TaskCompletionSource<bool>();
        http.RequestCompleted += (result, code, headers, body) =>
        {
            if (result == (long)HttpRequest.Result.Success)
            {
                var file = FileAccess.Open(savePath, FileAccess.ModeFlags.Write);
                file.StoreBuffer(body);
                file.Close();
                tcs.SetResult(true);
            }
            else
            {
                tcs.SetResult(false);
            }
        };

        http.Request(url);
        return await tcs.Task;
    }
}

数据迁移——存档格式变了怎么办

当新版本改变了存档格式，老玩家的存档在新版本上可能读不出来。必须做数据迁移：

// v1.0 的存档格式
{
    "version": 1,
    "player_level": 15,
    "gold": 1000
}

// v2.0 的存档格式（新增了经验值字段，金币改名为 coins）
{
    "version": 2,
    "player_level": 15,
    "experience": 2500,
    "coins": 1000,
    "achievements": []
}
C
// 存档迁移器
using Godot;
using System.Text.Json;

public partial class SaveMigrator : Node
{
    private const int CurrentSaveVersion = 2;

    public string Migrate(string oldJson)
    {
        var json = Json.ParseString(oldJson);
        int version = json.GetProperty("version").GetInt32();

        // 逐版本迁移
        while (version < CurrentSaveVersion)
        {
            version++;
            json = MigrateToVersion(json, version);
            GD.Print($"存档已迁移到版本 {version}");
        }

        return JsonSerializer.Serialize(json, new JsonSerializerOptions { WriteIndented = true });
    }

    private JsonElement MigrateToVersion(JsonElement data, int targetVersion)
    {
        // 这里需要用 mutable 的方式操作 JSON
        // C# 中建议使用 JsonNode 或 JsonDocument 来修改

        switch (targetVersion)
        {
            case 2:
                // v1 → v2：新增 experience 字段，gold 改名为 coins
                // 根据等级计算经验值
                // gold 字段复制为 coins
                GD.Print("迁移 v1 → v2：添加经验值，重命名字段");
                break;
        }

        return data;
    }
}

存档迁移的铁律

  1. 永远不要修改原始存档文件——先备份，再迁移，失败了可以恢复
  2. 迁移必须是幂等的——同一个存档迁移两次结果一样
  3. 测试老存档——每次发布前，拿真实的老存档测试迁移逻辑
  4. 保留老版本代码——不要删除旧版本的存档读取代码，直到确认所有玩家都迁移完成

发布流程总结

1. 开发完成 → 内部测试
2. 构建新版本包体（APK/EXE/Web）
3. 准备灰度配置（百分比、策略）
4. 上传到分发服务器
5. 开启 1% 灰度
6. 监控崩溃率、错误日志、玩家反馈（至少观察 24 小时）
7. 逐步扩大到 5% → 10% → 30% → 50%
8. 确认无问题后，全量发布 100%
9. 发布完成后继续监控 48 小时

检查清单

下一章

游戏能安全更新了。但玩家数量暴增后，服务器能扛住吗？下一章解决高并发问题。

→ 16. 高并发与高请求

最近更新:
贡献者: zefeng.peng
EVOCOSMOS
Copyright © 2026 EVOCOSMOS