排查和调试 Unity 播放器

Rider 的附加到 Unity 进程对话框会列出当前网络上运行的所有 Unity 实例。这包括 Unity 编辑器和任何帮助程序，以及任何独立或设备播放器。然后还会列出所有 USB 设备，最后列出其他项目。在显示 iOS USB 设备时，请注意 Rider 仅显示设备本身，无法识别 Unity 项目是否正在运行。

更多详情请参阅本文博客。

尽管可以在此处启动对当前项目编辑器实例的调试，更方便的做法是使用附加到 Unity 编辑器或附加到 Unity Editor 并运行运行配置，然后点击调试按钮即可自动附加。

故障排除

我的设备未显示在列表中

要成功调试播放器，必须满足以下条件：

播放器必须选择开发版构建和脚本调试复选框进行构建。 Rider 只会列出开发版构建，但会将禁用脚本调试的播放器显示为灰色。
基于 IL2CPP 的播放器需使用 Unity 2018.2 或更高版本来构建，从而支持 Mono 调试协议。
联网播放器需处于同一子网。例如，如果台式机的 IP 地址为 192.168.1.200 ，则播放器的 IP 地址也必须在 192.168.1.x 范围内。
联网播放器可能会因防火墙而被阻止。播放器在运行时会持续广播 UDP 消息，请确保防火墙未阻止 UDP 消息。 UDP 消息只会在当前子网内广播，请确保播放器与 Rider 运行的台式机处于同一子网。
iOS USB 调试在 Mac 和 Linux 上开箱即用，但在 Windows 上需要 iTunes 或 Apple Mobile Device Service。还需在主 Unity 安装过程中安装 iOS 构建支持模块。
在 Apple Silicon 上进行 iOS USB 调试需要 Rider 2021.3 或更高版本。如果以原生 Apple Silicon 应用运行 Rider，则需要 Unity 2021.2 或更高版本。以 Rosetta 2 应用运行 Rider 时，可以兼容旧版本的 Unity。
Nintendo Switch 开发者套件有有线和无线两种网络接口。 UDP 消息通过 Wi-Fi 连接广播，调试前请确保已配置好两种网络。

调试未显示所有字段和属性

调试播放器或设备时，大多数调试功能应可用，但由于不同平台构建要求不同，可能并非所有字段、属性和方法都可用。例如，IL2CPP 构建会进行代码裁剪以移除未使用的代码。这可能导致调试器无法评估某些类型或类型成员。

未找到该断点关联的模块

这种情况可能由多种原因导致：

IL2CPP 后端只能通过附加（issuetracker.unity3d ）调试。可以考虑使用 env.var。 UNITY_GIVE_CHANCE_TO_ATTACH_DEBUGGER=1 以从第一帧开始调试。
调试目标为 Apple silicon 的应用并配合 Intel UnityEditor（问题）

手动配置

如果 Rider 无法找到播放器或设备并在对话框中显示，仍可通过手动输入详细信息调试该播放器。播放器使用标准的 Mono 调试协议，因此需要主机地址和端口来启用调试。可在播放器日志中找到这些信息，并可通过如 logcat 或 XCode 等工具获取。

在对话框中使用手动添加玩家地址选项以指定详细信息。

也可使用 Mono 远程调试运行配置为播放器设置持久的运行配置。

防火墙

防火墙可能阻止设备并导致其无法在 Rider 的附加到 Unity 进程对话框中显示。 Mono 调试协议通过播放器指定的端口建立简单的 TCP 流量。只要该端口开放，则可进行调试。

如果防火墙阻止 UDP 或 IGMP（Internet Group Membership Protocol）消息，播放器可能无法显示在列表中。请妥善更新系统防火墙设置。

macOS

macOS 防火墙实际上有两个，其中只有一个有用户接口。

可以在安全 & 隐私系统偏好设置面板配置的防火墙是应用程序防火墙，这是一种粗粒度的防火墙，可以按应用允许或阻止入站连接。默认关闭（建议的原因是防火墙只有在有服务无必要侦听开放端口时才有用），但可以轻松启用。一般不会导致阻止列出 Unity 播放器所需的 UDP 组播包的问题，但如果启用了此防火墙，请确保 Rider 能接受入站连接。（可参阅此处"Firewall"技术概述。）

第二种防火墙是 PF 数据包筛选器，其灵活性更高。但默认配置可能会阻止 Unity 播放器在 Rider 的对话框中显示。

PF 默认禁用，但可以被系统组件启用。例如，当选中"阻止所有入站连接"或"启用隐藏模式"复选框时，应用程序防火墙会启用 PF。 PF 也会被 Internet 共享功能使用，即使未开启也可能被启用。

可以通过调用 pfctl -s info 检查 PF 是否启用（需 root 权限，因此通常需使用 sudo pfctl -s info）。

PF 的启用状态与应用程序防火墙状态互不影响。关闭应用程序防火墙时不会禁用 PF，需要单独控制。

PF 的默认配置文件为 /etc/pf.conf ，不设置任何规则，但定义了一些 "anchors"，以便系统动态添加规则（如 Internet 共享规则）。这些 anchors 在 /etc/pf.anchors/com.apple 中定义。可以通过 pfctl -s all 查看当前规则和统计信息，但只会显示当前 anchor 的规则，anchor 类似于容器。可使用该 pfdump.sh 脚本递归调用 pfctl 以显示所有已定义的规则。

启用后，若数据包不匹配现有规则，将被允许通过防火墙，除非数据包包含 IP 选项。来自 man pf.conf ：

allow-opts
      By default, IPv4 packets with IP options or IPv6 packets with rout-
      ing extension headers are blocked.  When allow-opts is specified
      for a pass rule, packets that pass the filter based on that rule
      (last matching) do so even if they contain IP options or routing
      extension headers.  For packets that match state, the rule that
      initially created the state is used.  The implicit pass rule that
      is used when a packet does not match any rules does not allow IP
      options.
            
   

遗憾的是，IGMP（Internet Group Membership Protocol）数据包使用 RA IP 选项，因此这些数据包将被丢弃。当 Rider（或其他软件）想要加入组播组以接收 UDP 消息时，必须发送 IGMP "join" 数据包。如启用 PF，此类 IGMP 出站数据包将被丢弃，组播组也未加入，导致收不到 UDP 组播消息。对 Rider 而言，即 Unity 播放器无法在对话框中显示。

可通过以下配置修复。请谨慎修改 /etc/pf.conf ，务必先做备份。此外，该文件每次系统更新都会被重建，因此此配置需定期重新应用。

请修改 /etc/pf.conf ，在文件末尾添加以下两行（编辑 pf.conf 文件需要 root 权限）：

anchor 'unity.udp/*'
load anchor 'unity.udp' from '/etc/pf.anchors/unity.udp'

然后添加一个名为 /etc/pf.anchors/unity.udp 的文件，内容如下：

#
# Unofficial configuration to enable Unity UDP multicast messages from players
#


# From `man pf.conf`:
#
#  allow-opts
#          By default, IPv4 packets with IP options or IPv6 packets with rout-
#          ing extension headers are blocked.  When allow-opts is specified
#          for a pass rule, packets that pass the filter based on that rule
#          (last matching) do so even if they contain IP options or routing
#          extension headers.  For packets that match state, the rule that
#          initially created the state is used.  The implicit pass rule that
#          is used when a packet does not match any rules does not allow IP
#          options.
#
# The last sentence means that when pf is enabled, the default rule will drop
# any packet that includes IP options. Multicast group membership is handled
# by sending IGMP report/leave packets, which use the RA IP option to inform
# a router that it needs to look at this packet.
# This rule will allow outgoing IGMP packets that have options and that have
# a destination of 225.0.0.222 - the multicast group used by Unity players.
# It is kept deliberately precise so that it does not affect other IGMP
# packets. It can be loosened to allow IGMP packets for other groups.
#
pass out proto igmp from any to 225.0.0.222 allow-opts label "Unity player UDP multicast"
            
   

该规则允许应用程序发送 IGMP 出站数据包，从而加入 225.0.0.222 UDP 组播组。这是 Unity 播放器所用的组。

然后重启 PF：

pfctl -d
pfctl -e -f /etc/pf.conf

支持

如本文无法解决您的问题，请通过 support@jetbrains.com 联系 JetBrains 支持。

2026年 5月 8日