跳到主要内容
版本：v4

PC 端游戏包体上传工具

TapRails 是 TapTap 平台提供的 PC 游戏包体上传工具，用于将 PC 端游戏包体上传至 TapTap 开发者中心。支持 Windows、macOS 和 Linux 系统，提供命令行界面，支持大文件分片上传。

环境要求​

  • 操作系统：Windows 7 或更高版本、macOS、Linux
  • 文件格式：支持 .zip、.7z 格式的游戏包体
  • 文件命名：仅支持字母、数字、下划线(_)、中横线(-)和点号(.)

准备工作​

1. 获取开发者资源​

在开始使用前，您需要：

  1. 在 TapTap 开发者中心 注册开发者账号
  2. 创建游戏应用并在「你的游戏」→「游戏服务」→「应用配置」获取以下信息：
    • App ID：应用的 ID
    • Client ID：应用的唯一标识符
    • Server Secret：用于 server to server API 调用的密钥

2. 下载工具​

  1. 访问 TapRails Releases 页面
  2. 根据您的操作系统选择对应的版本：
    • Windows: taprails-windows-amd64.zip
    • macOS (Intel): taprails-darwin-amd64.zip
    • macOS (Apple Silicon): taprails-darwin-arm64.zip
    • Linux: taprails-linux-amd64.zip
  3. 解压工具包到对应目录

使用说明​

1. 配置文件​

推荐通过命令行参数传入配置；也可以参考 config.json.example 创建 config.json，保存不经常变化的配置：

{
  "file": "game.zip",
  "package_version": "1.0.0",
  "app_id": 12345,
  "client_id": "从开发者中心「游戏服务」→「应用配置」获取的 client_id",
  "server_secret": "从开发者中心「游戏服务」→「应用配置」获取的 server_secret",
  "chunk_size": 104857600,
  "launch_exe": "game.exe",
  "launch_args": ""
}

配置项与命令参数：

命令行参数config.json 配置项最终必须有值说明
--file / -ffile✅游戏包体文件路径 (.zip/.7z 格式)
--package-version / -ppackage_version✅游戏包体版本号，须符合 semver 规范
--app-idapp_id✅应用 ID，从开发者中心获取
--client-idclient_id✅Client ID，从开发者中心「游戏服务」→「应用配置」获取
--server-secretserver_secret✅服务端密钥，从开发者中心「游戏服务」→「应用配置」获取
--chunk-sizechunk_size✅分片上传的分片大小，单位字节
--launch-exe / -elaunch_exe✅启动项可执行文件相对路径
--launch-args / -alaunch_args✅启动参数；无启动参数时传 ""
--config / -c不适用❌配置文件路径
--verbose / -v不适用❌显示详细日志

TapRails 只读取命令行参数和 config.json。同一配置项可以写在 config.json，也可以通过命令行参数传入；命令行传入时覆盖 config.json 的值。

2. 命令行使用​

# 基本用法
./taprails-cli upload --config config.json

# 显示详细日志
./taprails-cli upload --config config.json --verbose

# 覆盖配置文件中的包体和版本号
./taprails-cli upload --config config.json --file /path/to/game.zip --package-version 1.0.1

# 覆盖配置文件中的启动项和启动参数
./taprails-cli upload --config config.json -e game.exe -a "-arg1 xxx -arg2 yyy"

# 不使用配置文件
./taprails-cli upload --file /path/to/game.zip --package-version 1.0.0 --app-id 12345 --client-id client-id --server-secret server-secret --chunk-size 104857600 -e game.exe -a ""

如果 --launch-args 需要传入 -arg1 xxx -arg2 yyy 这类参数，请整体放在一组引号中。

版本号规范​

版本号必须符合 语义化版本控制 (semver) 规范。

输出示例​

成功上传​

Uploading large-game.zip (250.25 MB) for app[12345]...
Getting upload token...
Uploading file...
Using multipart upload (file size: 250.25 MB, chunk size: 100.00 MB)
Uploading chunks [████████████████████████████████████░░░░░░░░░░░░░░] 66.7% (2/3)
Completing multipart upload...
File uploaded successfully

常见问题​

配置相关​

  • 验证 app_id 是否有效
  • 检查 client_id 和 server_secret 是否正确
  • 检查分片大小是否过大