官方文档：抖音小游戏Unity WebGL分包工具
本文为实践记录，补充了官方文档中未提及的细节和常见问题解决方案

前言

作为一名Unity开发者，最近在尝试将WebGL游戏发布到抖音小游戏平台时，遇到了Wasm网络波动大导致连不上抖音服务器的问题，抖小技术小哥建议用命令行打包。抖音官方提供了分包工具来解决这个问题，但命令行版本的使用过程中踩了不少坑。本文将分享完整的实践过程，帮助大家避坑。

环境准备

安装Node.js环境

# 检查Node.js和npm是否安装
node -v
npm -v

如果没有安装，请前往官网下载：https://nodejs.org/
推荐安装LTS版本（长期支持版）

注意：安装时务必勾选”Add to PATH”选项，否则后续命令无法使用。

安装抖音命令行工具

# 安装分包工具
npm install -g @open-dy/tt-wasmsplit-ci

# 安装小游戏IDE命令行工具
npm install -g tt-minigame-ide-cli

# 验证安装
tt-wasmsplit-ci --version
tmg --version

常见问题：

  • 如果提示命令不存在，请将npm全局路径添加到环境变量：
# 获取npm全局路径
npm config get prefix

# 将返回的路径（如C:\Users\用户名\AppData\Roaming\npm）添加到系统PATH
  • 安装失败可尝试使用淘宝镜像：
npm config set registry https://registry.npmmirror.com/
npm install -g @open-dy/tt-wasmsplit-ci @open-dy/tmg-cli

完整分包流程

步骤1：登录开发者账号

tmg login -m

执行后会提示输入手机号发送验证码，再输入验证码即可

步骤2：初始化分包

tt-wasmsplit-ci init -p <WebGL包路径> -i <AppID> -m <版本描述>

参数详解：

  • -p：Unity导出的WebGL压缩包路径（必须是目录路径，不是压缩包！）也就是工程中project.config.json下的webgl路径zip
  • -i：小游戏AppID（在抖音开发者平台查看）
  • -m：版本描述（如”测试分包”）
    示例：
tt-wasmsplit-ci init -p "D:\game_build\webgl_package-20260206_144627.zip" -i tt1234567890abcdef -m "首次分包"

步骤3：生成预览码收集函数

tmg preview <Unity工程根目录>

此命令会生成一个二维码，使用抖音App扫码，在真机上运行游戏。
收集函数要点：

  1. 尽可能覆盖游戏所有功能
  2. 确保进入所有核心场景
  3. 触发所有关键交互
  4. 完成收集后关闭游戏

步骤4：执行分包

tt-wasmsplit-ci dosplit -p <原始WebGL包路径> -i <AppID> -m <版本描述>

参数注意：

  • -p 这里需要的是原始WebGL包的压缩文件路径（.zip格式）
  • -i 和 -m 与init命令保持一致

示例：

tt-wasmsplit-ci dosplit -p "D:\game_build\webgl_package-20260206_144627.zip" -i tt1234567890abcdef -m "1.0.0正式版"

分包过程：

  1. 命令执行后需等待5-10分钟
  2. 完成后会在当前目录生成分包后的zip包
  3. 包名通常包含 webgl_split 前缀

步骤5：上传到平台

# 进入Unity工程根目录（project.config.json同级目录）
cd D:\game_project

# 执行上传命令
tmg upload -v <版本号> -c <版本描述>

示例：

tmg upload -v 1.0.0 -c "1.0.0版本测试命令行打包"

常见问题解决方案

  1. 命令不存在问题 
    # 解决方案：
npm install -g @open-dy/tmg-cli @open-dy/tt-wasmsplit-ci
# 然后检查全局路径是否在系统PATH中
  2. 登录认证失败 
    # 清除缓存后重新登录
tmg logout
tmg login -m
  3. 分包初始化失败 
    # 检查点：
- 路径是否正确（使用绝对路径）
- 路径是否为目录（不是zip）
- 路径是否包含中文或特殊字符

结语

通过命令行工具实现抖音小游戏分包，可以大大提高开发效率，特别适合自动化构建流程。本文记录了我实践过程中遇到的各种问题及解决方案，希望能帮助大家少走弯路。
经验总结：

  1. 路径处理要格外小心
  2. 确保登录状态有效
  3. 真机收集函数要全面
  4. 分包过程需要耐心等待
  5. 善用调试参数排查问题