【Unity实战】如何使用VS Code在真实Android设备上调试 Unity应用

简介

本文介绍两种通过 VS Code 调试运行在真实 Android 设备上 Unity C# 脚本的方法：先展示"直接连接"（直接用设备 IP / Wi‑Fi）可行时的配置和步骤，接着讲更可靠的"adb forward（USB 端口转发）"方法。并包含自动检测 Unity 实际调试端口的脚本、launch.json 与 tasks.json 示例，以及常见问题与解决办法。

前置条件（都适用）

Unity 项目可构建 Android，并使用 Mono 脚本后端（若使用 IL2CPP，托管 C# 调试不可用）。
已安装 Android SDK / Platform Tools，adb 可用。
已安装 VS Code，并建议安装扩展：Debugger for Unity（vstuc）。
设备已开启开发者选项与 USB 调试（若用 Wi‑Fi，需先设置无线调试）。

一、方法 A --- 直接连接（设备 IP / Wi‑Fi）

注意：直接连接在某些网络/设备/Unity 配置下可能无法使用，但当设备与开发机在同一局域网并且 Unity 在设备上将调试端口绑定到可被外网访问的接口时，可直接连接。

步骤（直接连接）

在 Unity 中启用：File → Build Settings → Android，勾选 Development Build 与 Script Debugging，并使用 Mono。
构建并安装 APK 到设备（Unity 的 Build And Run 或手动安装）。
确认设备 IP（例如 192.168.1.100）：
bash 复制代码
```
adb shell ip -f inet addr show wlan0
```
或在设备 Settings → About → Status 中查看 IP。
在设备日志中查找 Unity 实际监听的端口（可能是 56000，或者 Unity 6.2 动态分配的端口）：
bash 复制代码
```
adb logcat | grep -i "Listening for debugger\|PlayerConnection"
```
你会看到类似：Listening for debugger on 127.0.0.1:56000 或 Listening for debugger on 192.168.1.100:56789。如果监听的是 127.0.0.1，直接远程访问通常不可行（见下说明）。
如果日志显示 Unity 在设备的可访问 IP（例如 192.168.1.100:56789）上监听，你可以在 launch.json 使用该 IP：
json 复制代码
```
{
  "name": "Attach to Unity (Network)",
  "type": "vstuc",
  "request": "attach",
  "endPoint": "192.168.1.100:56789"
}
```
在 VS Code 中选择这个配置并启动附加。

直接连接可行性的说明与限制

若 Unity 把监听地址绑定到 127.0.0.1（本地回环），你的主机无法直接通过设备 IP 访问该端口 ------ 此时需要端口转发（下一节）。
即使设备 IP 在同一 Wi‑Fi 网络，Android 的网络策略或应用权限也可能阻止外部访问该端口。
因此直接连接只在满足"Unity 在设备上绑定外网可达地址且网络可达"的条件下生效，现实中很多场景需转发。

二、方法 B --- 推荐：使用 adb forward（USB / 更可靠）

概念：用 adb forward 将设备上 Unity 实际监听的端口（例如 56000 或动态端口）映射到本机的某个端口（通常同 56000），然后在 VS Code 指向 127.0.0.1:端口 进行附加。USB 情况下最稳定、推荐使用。

步骤（adb forward）

确认设备已连接并被 adb 识别：
bash 复制代码
```
adb devices
```
在设备上启动/运行应用（确保是 Development Build + Script Debugging）。
查看设备日志得到 Unity 实际监听端口（如果 Unity 6.2 可能是动态分配）：
bash 复制代码
```
adb logcat | grep -i "Listening for debugger\|PlayerConnection" -m 1
```
提取出端口号，例如 56789。
建立本地转发（若你拿到的端口是 56789）：
bash 复制代码
```
adb forward tcp:56789 tcp:56789
```
或如果你想把设备端口 56789 映到本机 56000：
bash 复制代码
```
adb forward tcp:56000 tcp:56789
```
在 launch.json 指向本地端口，例如：127.0.0.1:56000。
在 VS Code 启动 Attach to Unity 配置，完成附加并开始调试。

为什么推荐 adb forward

适用于 USB（无需设备可达 IP）。
绕开 Android 的网络约束、应用绑定到回环或防火墙问题。
更稳定、跨设备和 Unity 版本兼容性好。

三、自动检测端口并自动转发的脚本（针对 Unity 6.2 动态端口）

下面提供一个简单的 shell 脚本 detect-and-forward.sh：它会读取设备日志以提取 Unity 实际监听端口并执行 adb forward，然后输出用于 launch.json 的地址。

脚本内容（保存为项目根目录可执行脚本，例如 scripts/detect-and-forward.sh）：

bash 复制代码

#!/usr/bin/env bash
# detect-and-forward.sh
# 用法: ./detect-and-forward.sh [local_port]
# 若未提供 local_port，使用 local_port = device_port

set -e

LOCAL_PORT=$1

# 清空缓冲日志，确保接下来的 logcat 输出是新启动的 app 日志
adb logcat -c

# 启动日志读取，等待包含 "Listening for debugger" 的行
echo "等待 Unity 日志以检测调试端口（最长等待 15 秒）..."
PORT_LINE=$(adb logcat -d | grep -i -m 1 "Listening for debugger" || true)

# 若未立即获取到，尝试短时间内轮询
if [ -z "$PORT_LINE" ]; then
  for i in {1..15}; do
    sleep 1
    PORT_LINE=$(adb logcat -d | grep -i -m 1 "Listening for debugger" || true)
    if [ -n "$PORT_LINE" ]; then
      break
    fi
  done
fi

if [ -z "$PORT_LINE" ]; then
  echo "未检测到 Unity 的监听日志，请确保应用已启动并启用 Script Debugging。"
  exit 1
fi

echo "找到日志: $PORT_LINE"

# 尝试提取端口号（匹配类似 :56000 或 :56789）
PORT=$(echo "$PORT_LINE" | grep -oE ":[0-9]{4,6}" | head -1 | tr -d ':')

if [ -z "$PORT" ]; then
  echo "无法从日志提取端口号，请手动检查 adb logcat 输出。"
  exit 1
fi

echo "检测到设备调试端口: $PORT"

if [ -z "$LOCAL_PORT" ]; then
  LOCAL_PORT=$PORT
fi

# 建立 forward
echo "执行 adb forward tcp:${LOCAL_PORT} tcp:${PORT}"
adb forward tcp:${LOCAL_PORT} tcp:${PORT}

echo "完成：请在 VS Code 使用 127.0.0.1:${LOCAL_PORT} 作为 endPoint"

将该脚本加入可执行权限：

bash 复制代码

chmod +x scripts/detect-and-forward.sh

然后你可以直接在终端运行：

bash 复制代码

./scripts/detect-and-forward.sh 56000

脚本会自动检测设备端口并把它转发到本机 56000；随后在 VS Code 的 launch.json 使用 127.0.0.1:56000。

四、示例 launch.json 与 .vscode/tasks.json（包括自动化）

launch.json（示例）：

json 复制代码

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach to Unity (Direct Network)",
      "type": "vstuc",
      "request": "attach",
      "endPoint": "192.168.1.100:56789"
    },
    {
      "name": "Attach to Unity (ADB Forwarded)",
      "type": "vstuc",
      "request": "attach",
      "endPoint": "127.0.0.1:56000",
      "preLaunchTask": "detect-and-forward"
    }
  ]
}

tasks.json（示例，把脚本作为 preLaunchTask）：

json 复制代码

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "detect-and-forward",
      "type": "shell",
      "command": "${workspaceFolder}/scripts/detect-and-forward.sh",
      "args": ["56000"],
      "isBackground": false,
      "problemMatcher": []
    },
    {
      "label": "adb-install-apk",
      "type": "shell",
      "command": "adb install -r ${workspaceFolder}/Builds/Android/YourApp.apk",
      "problemMatcher": []
    }
  ]
}

注意：detect-and-forward 脚本等待 adb logcat 输出，若你希望任务在启动前先安装 APK，可把 adb-install-apk 手动执行或创建复合任务/脚本来先安装再检测。

五、常见问题与解决

未能直接用设备 IP 连接：
- 检查 Unity 是否监听在 127.0.0.1（若是则无法直接远程访问）。
- 检查设备与主机是否在同一网段，是否有防火墙或路由隔离。
"Failed to attach debugger to 127.0.0.1:56000"：
- 确保 adb forward 成功并且 adb forward --list 能看到映射。
- 确保应用为 Development Build + Script Debugging。
- 使用 adb logcat 查找 Unity 实际监听端口。
端口每次不同（Unity 6.2 动态端口）：
- 使用上面提供的自动检测脚本或在设备日志中读取端口并转发。
- 如果想固定端口，可尝试在设备上设置 Unity 的调试端口（若 Unity 6.2 支持通过属性或环境变量设置），或在应用启动时传递参数（需工程级支持）。
断点不生效：
- 确保源码与已安装 APK 的版本一致，重新构建并部署 Development Build。
- 确认 VS Code 所使用的工作目录与项目文件匹配（符号路径一致）。

六、快速命令汇总

bash 复制代码

# 列设备
adb devices

# 查看 Unity 日志中调试端口
adb logcat | grep -i "Listening for debugger" -m 1

# 将设备端口转发到本机
adb forward tcp:56000 tcp:56000

# 删除转发
adb forward --remove tcp:56000

# 安装 APK
adb install -r /path/to/YourApp.apk

结语与建议

如果你的设备在 Wi‑Fi 下且 Unity 显示监听设备 IP（非 127.0.0.1），可以尝试直接在 launch.json 用设备 IP；但在绝大多数场景（尤其 USB）使用 adb forward 更可靠。