diff --git a/docs/树莓派4B部署注意事项.md b/docs/树莓派4B部署注意事项.md
index eba3051..2d7b964 100644
--- a/docs/树莓派4B部署注意事项.md
+++ b/docs/树莓派4B部署注意事项.md
@@ -32,9 +32,9 @@
 
 ```text
 # requirements-pod.txt(桥接最小集)
-mavsdk
+mavsdk<4    # ⚠ 锁版本,原因见 §3
 pyserial
-pytest    # 仅上机自测需要,部署运行可省
+pytest      # 仅上机自测需要,部署运行可省
 ```
 
 - `pod_bridge` 本身纯 Python + 惰性导入:`pyserial` 只在 `PodSerial` 实例化时加载,
@@ -46,29 +46,24 @@ pytest    # 仅上机自测需要,部署运行可省
 
 ## 3. MAVSDK 在 ARM 上的坑
 
-- pip 的 `mavsdk` 包内嵌 `mavsdk_server` 二进制;**aarch64 有官方 wheel**
-  (PyPI 核对:mavsdk 4.0.0 提供 `cp38-abi3 manylinux2014_aarch64`,
-  abi3 兼容 Python 3.11/3.13,要求 glibc≥2.17)。32 位 armv7l 支持不稳定——
-  这是必须 64 位镜像的主因。
-- **libstdc++ 符号**:wheel 内嵌库要求 GCC≥12 的运行时符号;官方镜像
-  Bookworm(GCC 12)/ Trixie(GCC 14)均满足,此前 Ubuntu 镜像上出现的
-  `undefined symbol: ..._M_futex_wait_until...` 不应复现。若仍报:
-  `ldd <libcmavsdk.so 路径> | grep stdc` 确认链接对象,必要时用
-  `LD_PRELOAD=/usr/lib/aarch64-linux-gnu/libstdc++.so.6` 兜底。
-- 安装后别只验证 import,要让原生库真加载一次。**mavsdk 4.x 已无独立
-  `mavsdk_server` 可执行文件**(2.x gRPC 架构的旧物),原生库是
-  `mavsdk/lib/libcmavsdk.so`,正确自检:
+- **mavsdk 4.x 是全新原生 API 重写,与经典 gRPC API 完全不兼容**(2026-09-24
+  树莓派实测):没有 `mavsdk.offboard` / `System` / `telemetry`,本仓库全部
+  飞控代码(Px4Gateway / MavsdkCommandGateway / test.py)都是经典 API,
+  装 4.x 直接 `LegacyModuleError`。**必须锁 `mavsdk<4`**(最新 3.17.4,
+  aarch64 官方 wheel `manylinux2014_aarch64`,PyPI 已核对);
+  32 位 armv7l 支持不稳定——这是必须 64 位镜像的主因。
+- 3.x 为 gRPC 架构,pip 包内嵌 `mavsdk_server` 可执行文件,**不加载
+  libcmavsdk.so,没有 libstdc++ 符号问题**——此前两系统上轮番出现的
+  `undefined symbol: ..._M_futex_wait_until...` 是 4.x 原生库专属坑,
+  换回 <4 后自然消失。
+- 安装后自检三步(缺一不可;单测全绿**不**证明 mavsdk 已装,测试已打桩脱钩):
 
   ```bash
-  # 复现设定点构造(原生库在此加载),打印 cmavsdk OK 即通过
-  python -c "from mavsdk import offboard; offboard.VelocityBodyYawspeed(0,0,0,0); print('cmavsdk OK')"
-  # 动态链接齐全性(无输出=齐全)
-  ldd ~/venv-pod/lib/python3*/site-packages/mavsdk/lib/libcmavsdk.so | grep "not found"
+  pip list | grep -i mavsdk           # 必须显示 3.x(如 3.17.4)
+  python -c "from mavsdk import System; print('api OK')"
+  find ~/venv-pod -name mavsdk_server # 应有输出;直接执行能起服务更佳
   ```
 
-  报 `undefined symbol` 按上面 libstdc++ 条目排查;`Exec format error` 是架构装错。
-  注意:单测全绿**不**证明 mavsdk 已装或原生库健康(测试已打桩脱钩),
-  本步不可替代。
 - 连接串写法(`pod_bridge.json` 的 `px4.connection_string`):
   - Pi 串口直连飞控 TELEM:`serial:///dev/ttyUSB0:57600`(波特率按飞控侧设置);
   - 经数传/仿真:`udp://:14540`。
diff --git a/requirements-pod.txt b/requirements-pod.txt
index ae99a8e..392710d 100644
--- a/requirements-pod.txt
+++ b/requirements-pod.txt
@@ -1,6 +1,6 @@
 # requirements-pod.txt —— 树莓派 4B(Ubuntu 24.04)吊舱桥接最小依赖
 # 只装这几个,切勿在 Pi 上装全量 requirements.txt(torch/cv2 无意义且数百 MB)
 # 详见 docs/树莓派4B部署注意事项.md §2
-mavsdk      # PX4 遥测订阅 + offboard 指令(aarch64 官方 wheel)
+mavsdk<4    # PX4 遥测订阅 + offboard;⚠ 必须锁 <4:v4 是全新原生 API 重写,与本仓库经典 gRPC API 不兼容(最新 3.17.4 有 aarch64 wheel)
 pyserial    # 吊舱串口(115200 8N1)
 pytest      # 仅上机自测(tests/pod_bridge 92 条)需要,部署运行可省
diff --git a/requirements.txt b/requirements.txt
index 1c7d90a..712b412 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -9,7 +9,7 @@ opencv-python           # camera.py / camera_test.py / video_test.py / demo_ster
 ultralytics
 
 # ---- 飞控通信(MAVSDK offboard -> PX4) ----
-mavsdk                  # test.py / demo_track_control.py / pod_bridge.px4_gateway
+mavsdk<4                # ⚠ 锁 <4:v4 为全新原生 API,经典 gRPC API(System/offboard/telemetry)已移除
 
 # ---- 吊舱串口(pod_bridge.pod_serial,惰性导入) ----
 pyserial