简介：面向飞行模拟器开发者与仿真系统集成人员的中文技术文档，聚焦 X-Plane 11（兼容 X-Plane 10 迁移场景）的 UDP 通信机制，帮助读者打通模拟器与外部程序之间的数据交互链路。文档系统梳理了端口 49000 的收发规则、字符串空值终止等关键约定，并逐一说明 ACFN、PREL、ACPR 等消息类型在加载与定位飞机结构时的用途，同时给出 RPOS 等数据输出指令的格式与经纬度、海拔、离地高度等字段定义，还提示了通过 error.out 日志排查通信故障的思路。资源包共 1 个 docx 文件，约 44KB，内容紧凑、查阅方便，适合作为手边速查手册。目前已有 2062 人学习，可供编写自定义座舱、运动平台或视觉驱动程序的读者参考借鉴。

1. 端口 49000 上的黑匣子：一份中文 UDP 文档能省掉多少试错

飞行模拟圈子里有个反直觉的现象：很多人把 X-Plane 当游戏玩，却不知道它从 V10 到 V11 一直把整个飞行模型敞开在 UDP 端口 49000 上。你不需要写插件、不需要碰 SDK，只要会发 UDP 包，就能让外部程序读取飞机的位置、姿态、速度，甚至反过来把一架飞机瞬移到指定经纬度。这份《X-Plane11_UDP通信的说明文档（中文）》干的就是这件事——把官方那套散落在论坛和头文件里的消息格式，整理成一份能照着拼包的中文说明。它适合三类人：想做移动地图或外部视景的开发者、想用自研飞控驱动 X-Plane 当可视化终端的仿真从业者、以及被结构体对齐坑过一遍想找份对照表的老手。下面按「消息怎么拼 → 收发怎么落地 → 坑在哪」拆开讲。

2. 消息封包格式：5 字符序言与结构体对齐

2.1 所有 UDP 消息共用的封包骨架

这份文档最值钱的地方，是把「所有消息长一个样」这件事说透了。发往 X-Plane 的每一条 UDP 消息，结构都是固定的三段：4 个字符的消息标签、1 个值为 0 的字节（空终止）、然后是这条消息对应的数据结构。收的时候也一样，X-Plane 回给你的包同样以 4 字符标签加一个 0 字节开头，后面跟数据体。

这个设计的好处是解析逻辑可以写成一套通用循环：读前 5 个字节判断消息类型，剩下的按类型查表解析。坏处是它对字节序和内存布局极其敏感，后面避坑章节会专门讲。

先看一个最小可运行的发送骨架，用 Python 写，因为改参数最快：

import socket import struct # X-Plane 默认监听 49000，目标 IP 填运行模拟器那台机器 XP_IP = "127.0.0.1" XP_PORT = 49000 def send_message(label: str, payload: bytes = b""): """label 必须是 4 个 ASCII 字符，第 5 字节补 0 作为空终止""" assert len(label) == 4, "标签必须正好 4 个字符" prologue = label.encode("ascii") + b"\x00" # 5 字符序言 sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM) sock.sendto(prologue + payload, (XP_IP, XP_PORT)) sock.close() # 示例：请求 X-Plane 每秒回传 60 次位置数据 send_message("RPOS", b"60\x00") # 频率字符串同样要空终止

逻辑说明：prologue就是文档反复强调的「4 字符标签 + 1 个 0 字节」。payload因消息而异，RPOS 这类「订阅型」消息的负载是一个空终止的十进制字符串，表示每秒回传次数；而 VEHX、DREF 这类「写入型」消息的负载是二进制结构体。参数上唯一要盯死的是标签长度——写成 3 个或 5 个字符，X-Plane 会直接当垃圾包丢掉，而且不报错，这是新手最常见的翻车点。

2.2 结构体对齐：为什么你的包大小总是不对

文档里花了大段篇幅讲 Intel 64 位下的结构体对齐规则，这不是啰嗦，是血泪经验。规则可以压缩成两句：整数和 float 按最近的 4 字节边界对齐，double 按最近的 8 字节边界对齐；结构体里一旦出现 double，它前面的 4 字节字段可能被填充到 8 字节边界。

拿 VEHX 消息（用外部飞行模型驱动 X-Plane 的飞机）举例，文档给的结构是：

struct vehx_struct { int p; // 飞机索引，0 是主飞机 double dat_lat; // 纬度，度 double dat_lon; // 经度，度 double dat_ele; // 海拔，米 float veh_psi_true; // 真航向，度 float veh_the; // 俯仰，度 float veh_phi; // 滚转，度 };

按对齐规则，p是 4 字节 int，但后面紧跟 double，所以编译器会在p后面塞 4 字节填充，让dat_lat落在 8 字节边界上。整个结构体实际占 4+4+8+8+8+4+4+4 = 44 字节。如果你在 Python 里用struct.pack("idddfff", ...)直接拼，得到的是 40 字节，少了那 4 字节填充，X-Plane 解析时字段全部错位，飞机要么不动要么飞到天外。

正确写法是显式补填充：

import struct def pack_vehx(p_idx, lat, lon, ele, psi, the, phi): # < 小端；i 后补 4x 填充，再跟三个 double 和三个 float fmt = "<i4xdddfff" return struct.pack(fmt, p_idx, lat, lon, ele, psi, the, phi) payload = pack_vehx(0, 39.9042, 116.4074, 35.0, 90.0, 2.0, 0.0) send_message("VEHX", payload)

4x就是那 4 个填充字节，<声明小端（x86 机器本地序）。参数含义：p_idx填 0 控制你正在飞的主飞机，1 到 19 控制其他飞机；经纬度用十进制度，海拔用米；三个姿态角用度。发出去之后，X-Plane 里那架飞机就会被你「遥控」到指定位置——这也是运动平台和外部视景最常用的反向驱动方式。

提示：不确定自己拼的包对不对，就去设置菜单的操作与警告页打开「转储网络数据到 log.txt」，发一次包，退出模拟器，打开日志看 X-Plane 认为收到的结构体大小是多少，和你发的字节数一比就知道差几个填充字节。

3. 订阅与写入：RPOS、RREF、DREF 三类消息的落地

3.1 RPOS 订阅位置：外部视景和移动地图的数据源

RPOS 是文档里出现频率最高的输出消息，因为它一次性给全了飞机的位置、姿态、速度和角速率，正好够驱动一个外部视景或移动地图。发RPOS加空终止的频率字符串，X-Plane 就会按这个频率把数据回传到「你发命令的那个 IP 和端口」——注意是回传到来源地址，不是固定端口，所以你的接收 socket 必须和发送 socket 绑在同一个本地端口上，否则收不到。

回传的数据体是紧密排列、无填充的：4 字符标签 + 1 个 0 字节，然后依次是 double 经度、double 纬度、double 海拔（米）、float 地形以上高度（米）、float 俯仰、float 真航向、float 滚转、float 东向速度、float 天向速度、float 南向速度、float 滚转角速率、float 俯仰角速率、float 偏航角速率。解析代码如下：

import socket import struct RECV_PORT = 49001 # 本地接收端口，必须和发送时用的源端口一致 sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM) sock.bind(("0.0.0.0", RECV_PORT)) sock.settimeout(2.0) # 从同一个 socket 发出订阅，X-Plane 才会回到这个端口 sock.sendto(b"RPOS\x0060\x00", ("127.0.0.1", 49000)) # 标签5字节 + 3个double + 10个float = 5 + 24 + 40 = 69 字节 FMT = "<5sddd10f" while True: data, addr = sock.recvfrom(1024) if len(data) < struct.calcsize(FMT): continue tag, lon, lat, ele, agl, pitch, hdg, roll, vx, vy, vz, p, q, r = \ struct.unpack(FMT, data[:struct.calcsize(FMT)]) if tag[:4] != b"RPOS": continue print(f"lat={lat:.6f} lon={lon:.6f} ele={ele:.1f}m hdg={hdg:.1f}")

逻辑说明：<5sddd10f里5s吃掉标签和空字节，ddd是三个 double，10f是后面十个 float。参数上要留意两点：一是频率字符串60表示每秒 60 次，设太高会拖慢模拟器本身，文档也提醒过转储日志会「让 sim 稍微变慢」；二是速度分量是机体坐标系下的东、天、南三向，不是地理坐标系，做航迹推算时别直接拿vx当正东速度用。

3.2 RREF 与 DREF：dataref 的读与写

RPOS 只覆盖位置姿态，想读发动机推力、襟翼角度、空速表这些细粒度变量，就得用 RREF。RREF 的负载是一个结构体：int 频率、int 使能码、char[400] 的 dataref 字符串。使能码是你自己编的整数，X-Plane 回传时会原样带回，用来区分你同时订阅的多个 dataref。数组型 dataref 在字符串末尾加[索引]，索引从 0 开始。

def subscribe_dataref(dref: str, freq: int, enable_id: int): # 频率4字节 + 使能码4字节 + 400字节字符串，共408字节 name = dref.encode("ascii")[:399] payload = struct.pack("<ii400s", freq, enable_id, name) send_message("RREF", payload) subscribe_dataref("sim/flightmodel/engine/POINT_thrust[1]", 10, 1001)

回传结构是 int 使能码 + float 值，共 8 字节，值一律按 float 给，哪怕原变量是整数。想停止订阅，把频率设成 0 再发一次同名 dataref 即可。

写入方向用 DREF，负载是 float 值 + char[500] 的 dataref 路径。文档特别强调这条消息要补空格凑满 509 字节，因为路径字段是定长的，不补零不补空格，X-Plane 可能读到脏数据。实操里我一般直接ljust到 500：

def set_dataref(dref: str, value: float): path = dref.encode("ascii")[:499].ljust(500, b"\x00") payload = struct.pack("<f500s", value, path) send_message("DREF", payload) # 打开左侧机翼防冰开关 set_dataref("sim/cockpit/switches/anti_ice_surf_heat_left", 1.0)

参数说明：value是 float，开关类变量用 0.0 和 1.0；路径必须和 dataref 列表里的拼写完全一致，大小写敏感，写错一个字母就是静默失败。DREF 能写的范围受模拟器约束，像马赫数这种由速度推导出来的量，你写进去也会被下一帧覆盖，文档里也点明了「有些消息会被 X-Plane 覆盖」。

3.3 CMND 与 DATA：命令触发和数据输出控制

CMND 的负载最简单，就是一个空终止的字符串，内容是 X-Plane 的命令路径，比如sim/flight_controls/flaps_up。命令路径去哪找？文档给的土办法很实用：进设置菜单的摇杆与设备页，切到按钮高级标签，屏幕上列出的组名加命令串就是完整路径。发CMND加\x00加命令串，等于替你按了一下那个按钮。

DATA 消息则是另一条路：它按「数据输出」屏幕里的索引来写值，结构是 int 索引 + float[8]。索引对应数据输出列表里的条目，-999表示放弃该条目的 UDP 控制、交还模拟器默认。这条消息适合你已经习惯用数据输出屏幕做硬件面板、又想用程序批量改值的场景。DSEL 和 USEL 用来动态增删要输出的条目，负载是一串 int，DSEL后跟0456就是选中列表第 4、5、6 项。这几条消息文档讲得比较散，实际用的时候建议先拿 DATA 单点验证，再上 DSEL 批量。

4. 避坑与排查：五个让包静默失效的细节

4.1 现象：包发出去了，X-Plane 毫无反应

原因：标签不是正好 4 字符，或者第 5 字节忘了补 0。X-Plane 对序言做严格匹配，长度不对直接丢弃，日志里也不一定留痕。解决：所有发送函数入口加断言，标签长度必须等于 4，序言统一用label.encode() + b"\x00"生成，别手写字符串拼接。

4.2 现象：RPOS 订阅成功但收不到回传

原因：发送和接收用了两个不同的 socket，源端口不一致。X-Plane 回传到「发命令的来源 IP 和端口」，不是固定端口。解决：像 3.1 节那样，同一个 socket 先bind本地端口再sendto，接收循环也用这个 socket。另外检查本机防火墙有没有拦入站 UDP。

4.3 现象：VEHX 发出去飞机乱飞或瞬移到离谱坐标

原因：结构体填充字节没算对，字段整体错位，X-Plane 把经度当成了纬度。解决：用struct.calcsize核对总字节数，VEHX 应为 44 字节；C 端用#pragma pack或手动补char pad[4]；发之前打开网络数据转储，比对日志里 X-Plane 期望的结构体大小。

4.4 现象：DREF 写 dataref 没效果

原因：路径拼写错误、大小写不符，或者路径字段没补满 500 字节导致尾部脏数据。解决：路径从 dataref 列表原样复制，写入前ljust(500, b"\x00")；先用 RREF 订阅同一个 dataref 读回当前值，确认路径有效再写。

4.5 现象：模拟器越跑越卡

原因：订阅频率设得过高，或者 RREF 订阅了几十个 dataref 还开着网络数据转储。解决：RPOS 一般 30 到 60 次每秒够用，RREF 按需给 1 到 10 次每秒；调试完记得把「转储网络数据到 log.txt」关掉，文档明确说过它会拖慢模拟器。

5. 从能收到能用：用日志反推结构体大小的验证习惯

把包发通只是第一步，真正让这套 UDP 通信稳定跑在项目里，靠的是一个笨办法：每次新增消息类型，先用日志反推结构体大小，再写解析代码。具体做法是打开网络数据转储，发一次目标消息，退出模拟器，打开日志文件搜你发的标签，X-Plane 会打印它期望的字节数和实际收到的字节数。两个数字一减，差几字节就是少补了几个填充。

我一般会把这个校验做成一张对照表，贴在代码注释里：

这张表不是让你背，是让你每加一条消息就补一行，半年后回头看就是自己的排错手册。另一个习惯是给每个订阅的 dataref 分配固定使能码并记在配置里，回传时先按使能码分发再解析，避免多个 dataref 混在一个接收循环里互相覆盖。

还有个容易被忽略的点：文档里从 V10 到 V11 的迁移说明提到一批旧消息被废弃，比如PAPT、PMAP、VEH1、VEHA都让位给PREL和VEHX，HACF、R_QT直接停用。如果你手上有 V10 时代的老代码，别指望原样跑在 V11 上，先按文档的对照把消息名换掉，再重新验证结构体——V11 的 ACFN 结构加了 livery 索引字段，字节数也变了。

从那以后我每次接一个新的 UDP 消息，都强制先跑一遍「发一次、转储、对数、再写解析」的流程，哪怕文档已经把结构写得很清楚。因为文档给的是规则，日志给的是你这台机器、这个编译器、这套语言下的真实字节数，两者对上了才算真的通了。希望这份拆解帮到你，少走几趟我当年踩过的填充字节弯路。

本文还有配套的精品资源，点击获取