抖小Unity WebGL分包命令行工具实践指南

官方文档：抖音小游戏Unity WebGL分包工具

本文为实践记录，补充了官方文档中未提及的细节和常见问题解决方案

前言

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

环境准备

1. 安装Node.js环境

bash 复制代码

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

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

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

2. 安装抖音命令行工具

bash 复制代码

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

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

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

常见问题：

如果提示命令不存在，请将npm全局路径添加到环境变量：
bash 复制代码

获取npm全局路径

npm config get prefix

将返回的路径（如C:\Users\用户名\AppData\Roaming\npm）添加到系统PATH

复制代码

- 安装失败可尝试使用淘宝镜像：
    ```bash
npm config set registry https://registry.npmmirror.com/
npm install -g @open-dy/tt-wasmsplit-ci @open-dy/tmg-cli

完整分包流程

步骤1：登录开发者账号

bash 复制代码

tmg login -m

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

bash 复制代码

### 步骤2：初始化分包
```bash
tt-wasmsplit-ci init -p <WebGL包路径> -i <AppID> -m <版本描述>

参数详解：

-p：Unity导出的WebGL压缩包路径（必须是目录路径，不是压缩包！）也就是工程中project.config.json下的webgl路径zip
-i：小游戏AppID（在抖音开发者平台查看）
-m：版本描述（如"测试分包"）
示例：

bash 复制代码

tt-wasmsplit-ci init -p "D:\game_build\webgl_package-20260206_144627.zip" -i tt1234567890abcdef -m "首次分包"

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

bash 复制代码

tmg preview <Unity工程根目录>

此命令会生成一个二维码，使用抖音App扫码，在真机上运行游戏。

收集函数要点：

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

步骤3：执行分包

bash 复制代码

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

参数注意：

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

bash 复制代码

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

分包过程：

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

步骤4：上传到平台

bash 复制代码

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

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

示例：

bash 复制代码

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

常见问题解决方案

1. 命令不存在问题

bash 复制代码

# 解决方案：
npm install -g @open-dy/tmg-cli @open-dy/tt-wasmsplit-ci
# 然后检查全局路径是否在系统PATH中

2. 登录认证失败

bash 复制代码

# 清除缓存后重新登录
tmg logout
tmg login -m

3. 分包初始化失败

bash 复制代码

# 检查点：
1. 路径是否正确（使用绝对路径）
2. 路径是否为目录（不是zip）
3. 路径是否包含中文或特殊字符

结语

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

经验总结：

路径处理要格外小心
确保登录状态有效
真机收集函数要全面
分包过程需要耐心等待
善用调试参数排查问题
如果遇到本文未覆盖的问题，欢迎在评论区交流讨论！