SteamOS Devkit Client 用法:连接、上传、调试、取文件

SteamDeck 不分开发机和零售机,零售机开了开发者模式同样能连 Devkit Client。整个开发循环就是:Devkit Client 连上 Deck → Title Upload 把游戏推上去 → 跑起来 → VS attach 调试 → scp/FileZilla 把日志和 dump 拿回来。

参考:https://partner.steamgames.com/doc/steamdeck/loadgames

装工具

开发机(PC):从 Steam 安装 SteamOS Devkit Client(确保 Steam 在运行),装完在 Steam 库的"软件"分类里启动。命令行启动方式:Windows 跑 windows-client/devkit-gui.exe,Linux 在 linux-client 目录跑 python3.9 ./devkit-gui-cp39.pyz。

测试机:有 SteamDeck 的话 SteamOS Devkit Service 已预装并运行,无需操作。

连接 Deck

前提:开发机和 Deck 必须在同一个允许多播 DNS(Multicast DNS)的局域网里才能被发现。公司网络下通常要找 IT 把开发机和 Deck 调到同一网段——可以用 Dock 有线接公司网络。

1. Deck 联网并更新到最新系统(Settings → System)。
2. Deck 上:Settings → System → 勾 Enable Developer Mode,然后 Settings → Developer → Pair new host。
3. 开发机上:Devkit Client 里找到你的 Deck(EV2 机显示 "callistoXXX",DV 机显示 "Valve Aerith"),点右侧 Register。看不到设备时用 Add by IP 字段手动填 IP。
4. Deck 上批准配对请求。

上传版本(Title Upload)

点 Title Upload 标签配置后上传。上传用的是 rsync over ssh,对内容改动少的重复上传很快。各选项:

• Local Folder — 含游戏运行所需全部文件的根目录。
• Upload filtering — 三选一:Exclude only(空格分隔的排除规律)、Include only(只传匹配的)、Rsync args(高级用户直接传 rsync 参数)。
• Clean upload — 删掉 Deck 上 Local Folder 里没有的文件。
• Start Command — 游戏的可执行文件加任意启动参数。
• Steam Play — 上传 Windows 二进制、需要 Proton 跑的勾这个。
• Steam Play debug — 勾上才能在 VS 里逐行调 C++。

注:如果已经有 appid 且用了 Steamworks API,要在上传根目录、可执行文件旁放一个只含 appid 的 steam_appid.txt。

配置可以 Save Config 存起来,用不同 Name 切换。上传成功后,Deck 的 Steam 库"非 Steam 游戏"分类里会出现以该 Name 命名的游戏(显示为 "Devkit Game: xxx")。

传到 SD 卡:Deck 上 Steam 键 → 电源 → 切换至桌面,桌面模式下进 Home > devkit-game 找到游戏文件,移到 SD 卡。如果库里找不到上传的游戏,在桌面模式 Steam 里"添加非 Steam 游戏",把要跑的 exe 加进去,再在 设置 → 属性 → 兼容性 里勾"强制使用兼容工具"。

两种调试方式

在 UE 编辑器里直接 launch

适合开发期快速跑。改 Engine.ini 加:

[SteamDeck]
+SteamDeckDevice=(IpAddr=192.168.0.10,Name=MySteamDeck,UserName=deck)

• IpAddr(必填)— Deck 的 IP。
• Name(可选)— UE 里显示的名字。
• UserName(必填)— 接入 UE 的 Deck,UserName 必须是 deck。

改完重启编辑器,Platforms 菜单里会出现你的 Deck,选它就能把项目 launch 到 Deck 上。

VS attach 远程调试

Devkit Client 上传时勾 "Steam Play" 和 "Steam Play Debug",上传后游戏在库的非 Steam 分类里。运行游戏后,VS 里 Debug → Attach to Process(Ctrl+Alt+P),找到 Steam Deck,选游戏进程 Attach。

找不到 Deck 时:确保机器没息屏、游戏已启动,Devkits 里刷新 Status 确认 Registered 连接没断。有些机器在 VS 里就是找不到,原因没查明。

调试进程启动(early attach):装对应版本的 VS 插件,Debug → Other Debug Targets → Child Process Debugging Settings 启用,上传时勾 "Wait for attach",启动游戏后在 VS 里 attach Steam.exe。

attach 调试的坑

• Debug 版本黑屏:上传 Debug 版到 Deck 后运行一直黑屏转 logo,Release 版正常。原因是 SteamOS 缺 Windows debug runtime(Proton 不带)。解法:把 "Copy C++ Runtime to OutDir" 改成 Yes(推荐,编译后把 C++ Runtime 重新上传),或把 "Use Debug Libraries" 改 No(不推荐,可能引入编译问题)。
• 远程调试工具:勾 "Steam Play" 时 devkit 会把 VS 的远程调试工具从开发机复制过去。官方说只从 VS 2019/2017 找已安装的调试工具,但实测 VS 2022 也能选且能正常用。
• 堆栈只有一层:通过 Remote Debugger 调 Deck 游戏时堆栈只能看到一层,Step into/Out 偶尔行为诡异,根因和解法都没找到。可以试试 VS 2017。

Steam Client Console(CEF Console)

要跑 Steam 客户端控制台命令时用 CEF Console:Devkit Client 连上后在 Devkits 标签点 CEF Console,会开个浏览器标签连到 Deck 的 CEF client,点 SP 打开主 UI 的标签,右侧有调试控制台。在 Console 里先 EnableSteamConsole(),之后 Steam 客户端 Console 的输出会以 SteamClient 高亮显示。执行命令要整条用双引号包进 SteamClient.Console.ExecCommand()。

参考:https://docs.unrealengine.com/5.3/zh-CN/steam-deck-quick-start-in-unreal-engine/

从 Deck 取文件

前提:Deck 和目标 PC 在同一网络环境才能互传。

scp

Windows 上开 cmd:

scp <username>@<deck_ip>:/home/steam.log D:\steam.log

源/目标格式是 用户名@IP地址:路径,本机一侧可以直接用相对路径。会要求输 Deck 的密码(输入时不显示位数,敲完回车即可)。Deck 没设过管理员密码就在桌面模式命令行 passwd 创建。

查用户名:桌面模式左下角呼出光标移到 SteamDeckUser 看,比如 deck@steamdeck 用户名就是 deck。

FileZilla

PC 装 FileZilla,Deck 上通过 Discover 装 FileZilla(顺便自动配好传输环境);不想装就在 Deck 上开 sshd:

sudo systemctl enable sshd
sudo systemctl start sshd

FileZilla 里填 Host(Deck IP)、用户名、密码,端口 22,Quickconnect 即可。

几个常用文件位置

截图:/home/deck/.local/share/Steam/userdata/<steam_user_id>/760/remote/<appid>/screenshots

存档:/home/deck/.local/share/Steam/steamapps/compatdata/<appid>/pfx/drive_c/users/steamuser/Documents/My Games/<GameName>/Steam/<steam_user_id>

Dump:部分游戏的 Debug 版本会把 .dmp 生成在游戏根目录。游戏 Crash 后会回到 Launcher,看到回 Launcher 就去根目录找 dump。提供 dump 时记得带上版本号,程序需要具体版本文件 + dmp 才能调。

截图取不到时通常是没开文件传输权限,按上面 sshd 的步骤开。