简介：面向飞行仿真初学者与需要快速搭建工程环境的开发者，这份 JSBSim 编程实践工程提供了一套可在 Visual Studio 2015 中直接打开、编译和运行的示例方案。核心是配置好 JSBSim 静态库的 VS2015 工程，分别附带 Release 与 Debug 两版库文件，便于理解两种构建模式下的链接差异；JSBSimTest.cpp 演示了库的调用方式，编译后即可执行简单飞行仿真，适合验证环境、学习接口调用与二次开发。压缩包共 615 个文件，约 49.01MB，以 xml 飞行模型与配置、h/hxx/cxx/c 源码及头文件为主，另含 lib 静态库、sln/vcxproj 工程文件、readme 说明与 bat 脚本等，类型覆盖较完整。已有 1774 人学习下载。读者可省去静态库编译与环境配置的反复试错，直接对照工程结构梳理依赖关系，在示例基础上替换飞行模型、调整仿真参数并调试，也能为课程实验、毕设或小型飞行仿真项目提供可复用的工程骨架。

1. 飞控算法写完了，拿什么验证它

飞控逻辑写完，手上没有真机，也没有商业飞行模拟器的授权，怎么验证一段爬升段的高度保持会不会发散？我一般会把 JSBSim 拉进来——一个开源的六自由度飞行动力学模型库，气动、推进、质量、重力、地面反作用力各算各的，最后合成位置和姿态。麻烦在于它在 VS2015 下编译是个体力活：字符集、运行库、根目录、飞行器数据，任何一项配错都只能对着控制台发呆。这份 JSBSim 编程实践工程把解决方案、编译配置和几个能直接跑的仿真脚本整理在一起，适合做飞控验证、航电联调、地面站原型的人，也适合想把 FDM 内核嵌进自己程序的开发者。后面按「工程怎么组织、怎么编、怎么跑、怎么改」的顺序拆，每一步都落到具体文件和参数上。

2. 工程定位与技术栈：JSBSim 到底站在仿真系统的哪一层

2.1 它不是一个游戏，是一台会算数的发动机

很多人第一次接触 JSBSim 会误以为它是个能出画面的飞行模拟器。不是。它输出的只有数字：位置、速度、姿态角、角速率、各轴加速度、发动机转速、油箱余量，一帧一帧往下推。画面是别人的事——视景引擎、地面站、仪表盘从它这里取属性值再画出来。这个定位决定了它的接口形态：没有渲染循环，没有窗口，只有一个FGFDMExec对象被你按时间步长反复调用。

它的内部是典型的「调度器 + 子系统」结构。FGFDMExec本身不参与任何物理计算，只负责按固定顺序调用一串FGModel派生类：大气模型FGAtmosphere先给出当前高度的密度和声速，风模型FGWinds叠加紊流，FGPropagate负责刚体运动学积分，FGAuxiliary把机体轴速度换算成迎角、侧滑角、动压，FGAerodynamics查表算气动力和力矩，FGPropulsion算推力，FGMassBalance算重心和转动惯量，FGGroundReactions处理起落架接触，最后FGAccelerations把力和力矩转成加速度。这个顺序不能乱，因为后一个模型的输入依赖前一个的输出。

工程里最有价值的东西不是这套算法本身——那是 JSBSim 上游的贡献——而是把这套结构在 VS2015 里跑通所需要的那一堆配置。多字节字符集还是 Unicode、静态运行库还是动态、Win32 还是 x64、包含目录怎么设、飞行器数据目录怎么指，这些在 Linux 下用 CMake 一行命令解决的事，在 VS 里要一个格子一个格子点。这份工程相当于把点过的格子存下来了。

2.2 解决方案的组织方式：一个 sln 带几个角色不同的 vcxproj

打开解决方案，你会看到它不是单一工程，而是按职责拆开的。核心是一个静态库或动态库目标，把src/FDM、src/math、src/models、src/input_output、src/simgear这些目录下的源文件编成JSBSim.lib；另一个是可执行的示例目标，链接前面那个库，写一个main把仿真的生命周期走一遍；通常还会有一个只做单元验证的小工程，用来单独调某个模型，比如只跑大气模型看不同高度下的密度对不对。

src/simgear这个目录值得单独说一句。JSBSim 早期从 FlightGear 项目里拆出来，依赖 SimGear 提供 XML 解析、路径处理、网络 socket、数学工具这些基础设施。如果按常规思路去外部装一遍 SimGear，版本对不上会连环报错。工程的做法是把用得到的那些源文件直接内嵌进来，sg_xml、sg_path、sg_misc各取所需，随主库一起编译。省掉了外部依赖，代价是编译单元变多，首次全量编译要等几分钟。

提示：内嵌的 SimGear 代码是精简过的，如果你从上游拉了新版 JSBSim 源码往这个工程里塞，先比一下src/simgear的文件清单，缺文件会在链接期以一堆sgPath::未定义符号的形式炸出来。

2.3 编译前必须钉死的四个开关

这四个开关不钉死，后面所有调试都是玄学。

第一是字符集。JSBSim 内部大量使用char*和std::string传路径、属性名、XML 节点名，VS 工程属性里的「字符集」必须设成「使用多字节字符集」。设成 Unicode 之后，sgPath的构造函数和LoadModel的字符串参数会在编译期或运行期出现宽窄字符转换问题，典型症状是明明文件在那儿，程序却说打不开。

第二是运行库。Debug 配置用/MDd，Release 用/MD，全解决方案必须一致。主库用/MT、示例工程用/MD，链接期就是LNK2005: _free 已经在 libcmt.lib 中定义，然后一路LNK1169。工程里已经在所有 vcxproj 上统一过，你要是新建一个工程往里加代码，记得手动改过来。

第三是平台。Win32 和 x64 的配置是分开存的，属性页里改了 x64 的包含目录，切到 Win32 就还是空的。新手最容易在这里翻车：Debug|x64 编过了，切到 Release|Win32 一堆找不到头文件。

第四是 C++ 标准。VS2015 默认开启部分 C++11/14 特性，auto、nullptr、范围 for、std::unique_ptr都能用，但std::make_unique是 C++14 的，VS2015 的库里有，编译器支持要看补丁版本。工程里的代码写法停留在 C++11 能覆盖的范围，避免用结构化绑定、if constexpr这些 VS2015 根本不认的语法。

3. 把工程跑起来：从打开解决方案到第一帧飞行数据

3.1 目录树里哪几个文件夹是活的

解压之后先别急着点生成，花两分钟认清目录。src是库的源码，src/FDM下面按模型分文件，src/math是向量矩阵四元数，src/input_output是脚本解析和输出通道，src/models是执行机构、滤波器、FCS 组件这些可复用的积木。aircraft目录放飞行器定义，每架飞机一个子目录，里面至少有一个*.xml描述几何、质量、气动表、发动机引用，可能还有Systems子目录放飞行控制系统的 XML 和脚本。engine目录放发动机模型，systems放通用系统，scripts放仿真脚本。

aircraft、engine、systems、scripts这四个目录合起来叫「根目录数据」，JSBSim 运行时按相对路径去找它们。工程里通过FGFDMExec::SetRootDir一次性指定根，剩下的SetAircraftPath、SetEnginePath、SetSystemsPath都是在根下面拼相对路径。很多人编译成功但一运行就报找不到飞机，十有八九是工作目录不对——VS 默认把工作目录设成$(ProjectDir)，而数据目录在上一层。

3.2 生成顺序与第一次编译

解决方案的依赖关系已经配好了，直接「生成解决方案」就行。首次全量编译大概三到五分钟，输出窗口会刷过几百个编译单元。如果中途中断在某个.cxx文件上，先看错误码：C1083是找不到头文件，去项目属性的「附加包含目录」里补src、src/simgear、src/simgear/xml这几条；C2065是标识符未声明，多半是某个#include被条件编译挡掉了。

编译通过之后，别急着跑示例程序。先在scripts目录下找那个最简单的脚本，用命令行方式跑一遍，确认库本身没问题：

# 在解决方案输出目录下执行，JSBSim.exe 是示例工程产物 # --root 指定数据根目录，--script 指定仿真脚本，--logdirect 让日志直接打到控制台 JSBSim.exe --root=..\..\ --script=scripts\c172_level_flight.xml --logdirect=1

--root后面的路径要指到包含aircraft、engine、systems、scripts的那一层，不是指到scripts里面。--logdirect=1关掉日志文件缓冲，出问题时能立刻在控制台看到Could not open file这类信息，比事后翻日志快得多。

3.3 用脚本驱动一次定高平飞

示例脚本的骨架是这样，XML 声明、use节点选飞机和初始条件、run节点定义时间窗和事件、output节点定义输出通道：

<?xml version="1.0" encoding="utf-8"?> <runscript name="c172_level_flight"> <!-- 选机型，并引用 aircraft/c172x/reset00.xml 里的初始条件 --> <use aircraft="c172x" initialize="reset00"/> <!-- 仿真时间窗：从 0 秒跑到 60 秒，步长 1/120 秒 --> <run start="0" end="60" dt="0.0083333"> <!-- 全程固定油门 75%，配平量给一点点抬头 --> <property value="0.75">fcs/throttle-cmd-norm</property> <property value="0.05">fcs/pitch-trim-cmd-norm</property> <!-- 第 10 秒触发一次爬升指令，验证高度环的响应 --> <event name="climb_cmd"> <condition>simulation/sim-time-sec >= 10.0</condition> <set name="fcs/pitch-trim-cmd-norm" value="0.18"/> </event> </run> <!-- CSV 输出，20Hz 采样，只记录关心的几个量 --> <output name="c172_level.csv" type="CSV" rate="20"> <property>simulation/sim-time-sec</property> <property>position/h-sl-ft</property> <property>velocities/vc-kts</property> <property>attitude/pitch-rad</property> <property>fcs/throttle-cmd-norm</property> </output> </runscript>

use节点里的initialize指向初始条件文件，这个文件定义空重、油量、初始高度、初始空速，缺一项 JSBSim 会用自己的默认值补，但默认值不一定合理，比如默认海拔是海平面、默认速度是零，飞机一上来就是静止的，气动表在零动压下算出来的力矩全是零，看起来「不动」，其实是没给初始状态。

run里的dt是积分步长，不是输出步长。输出频率由output节点的rate决定，两者独立。dt取 1/120 是这类固定翼模型的常规值，再大容易出现数值不稳定，再小对精度提升有限但计算量翻倍。property节点给常量赋值，event节点挂条件触发，条件里用的属性名必须是属性树里真实存在的，写错了不会报错，只是永远不触发——这是排查时最容易忽略的一类静默失败。

output里的type除了CSV还支持TECPLOT、SOCKET、NONE，接外部程序时用SOCKET把每帧状态推出去，做批量扫描时用CSV落盘后处理。

3.4 看输出：怎么判断这一跑是不是可信

CSV 出来之后先看三件事。时间列是不是等间隔、有没有跳变，跳变说明某一帧Run()返回了 false 被跳过，通常是某个模型内部做了数值保护。高度曲线在爬升指令之后应该是单调上升到新的配平点附近，出现周期性振荡说明俯仰阻尼不够或者配平量给大了。空速和油门的联动关系要合理，油门加到 75% 而空速纹丝不动，多半是推进模型没加载成功，推力一直是零。

我一般还会顺手看一眼俯仰角的稳态值。定高平飞时俯仰角应该在 2 到 5 度这个量级，如果稳定在 15 度以上，说明升力系数表或者重心位置有问题，飞机在用大迎角硬撑。这类问题在曲线上不明显，但换成三维视景就是机头翘得离谱。

注意：CSV 里的单位是英制的，高度英尺、速度节、角度弧度、力矩磅英尺。写后处理脚本时别按米和公里每小时去解读，不然会得出「这飞机在 3000 米高空以 120 公里每小时巡航」这种结论。

4. 核心代码拆解：一帧仿真到底发生了什么

4.1 FGFDMExec 的生命周期：创建、装载、跑、销毁

外部程序嵌 JSBSim，入口永远是FGFDMExec。下面这段是最小可用骨架，每一步都有它的必要性：

#include "FGFDMExec.h" #include "FGInitialCondition.h" #include "sg_path.h" int main() { // 1. 创建调度器，构造时会把各子系统 new 出来，但不加载任何数据 JSBSim::FGFDMExec* fdm = new JSBSim::FGFDMExec(); // 2. 指定根目录。必须指到包含 aircraft/engine/systems 的那一层 fdm->SetRootDir(SGPath("./")); // 3. 加载机型。内部会去 aircraft/<name>/ 下找同名 xml if (!fdm->LoadModel("c172x")) { printf("load model failed\n"); return -1; } // 4. 设积分步长，1/120 秒是固定翼常用值 fdm->Setdt(1.0 / 120.0); // 5. 通过初始条件对象设置初始状态，再 RunIC 让它生效 JSBSim::FGInitialCondition* ic = fdm->GetIC(); ic->SetAltitudeFtIC(3000.0); // 初始高度 3000 英尺 ic->SetVcalibratedKtsIC(110.0); // 初始校准空速 110 节 ic->SetHeadingDegIC(90.0); // 初始航向正东 if (!fdm->RunIC()) { printf("initial condition failed\n"); return -1; } // 6. 主循环：每一帧先写输入，再 Run，再读输出 for (int i = 0; i < 120 * 60; ++i) { fdm->SetPropertyValue("fcs/throttle-cmd-norm", 0.75); if (!fdm->Run()) break; // 返回 false 表示某模型拒绝了这一帧，通常要查日志 double alt = fdm->GetPropertyValue("position/h-sl-ft"); double ias = fdm->GetPropertyValue("velocities/vc-kts"); if (i % 120 == 0) { printf("t=%.1f alt=%.1f ias=%.1f\n", i / 120.0, alt, ias); } } delete fdm; return 0; }

SetRootDir用SGPath而不是std::string，是因为sgPath内部做了平台路径分隔符归一化，Windows 下反斜杠、Linux 下斜杠，统一走它省得自己处理。LoadModel返回 bool，失败不会抛异常，只会往日志里写一行，所以这个返回值必须判。

RunIC这一步很多人会漏。只调SetAltitudeFtIC不调RunIC，初始条件只是存进了对象里，没有真正作用于状态向量，第一帧开始跑的时候飞机还在默认的海平面静止状态。这个坑的表现是「我明明设了 3000 英尺，输出里高度一直从 0 开始爬」。

Run()返回 false 的情况要区分对待。有些是模型主动拒绝，比如发动机熄火后推进模型返回 false；有些是数值溢出触发了保护。前者是正常业务，后者要查参数。我的习惯是在循环里统计连续 false 的次数，超过阈值就停下来打日志，而不是一路break掉把问题掩盖了。

4.2 Run() 内部：模型链是怎么串起来的

Run()的实现很短，核心就是按固定顺序调一串Run()：

bool FGFDMExec::Run(void) { bool result = false; // 每帧开始先刷新时间，所有模型都依赖这个 if (Frame == 0) { // 首帧走特殊路径，做一次完整的初始化 result = RunIC(); } else { // 常规帧：按依赖顺序逐个推进 result = true; result &= Atmosphere->Run(); // 大气：密度、温度、声速 result &= Winds->Run(); // 风：常值风 + 紊流叠加 result &= Propulsion->Run(); // 推进：油门 -> 推力 result &= MassBalance->Run(); // 质量：燃油消耗 -> 重心、惯量 result &= Aerodynamics->Run(); // 气动：迎角侧滑角 -> 力与力矩 result &= FlightControl->Run(); // 飞控：指令 -> 舵面偏度 result &= GroundReactions->Run(); // 地面：起落架接触力 result &= Propagate->Run(); // 运动学：力 -> 加速度 -> 速度 -> 位置 } // 每帧末尾统一刷一次输出通道 for (unsigned int i = 0; i < Outputs.size(); ++i) { Outputs[i]->Run(); } Frame++; return result; }

这张调用顺序表就是整个仿真的骨架。Atmosphere排第一是因为气动力要靠密度算动压；Propulsion排在Aerodynamics前面，是因为推力线的安装角会影响气动力矩；FlightControl排在Aerodynamics之后但在Propagate之前，是因为这一帧算出来的舵面偏度要立刻作用到下一帧的气动力上，而位置积分用的是这一帧已经算好的合力。

result &=这种写法意味着任何一个模型返回 false，整帧就标记为失败，但后续模型仍然会被调用。这是有意为之：让所有模型都把这一帧走完，日志里能看到完整的失败链，而不是在第一个失败点就中断。代价是失败帧的状态向量可能是半更新的，如果你在外面拿到 false 还继续用当前状态，数据就不干净了。

理解了这个顺序，很多现象就好解释了。比如你改了一个气动系数，输出的高度响应要过一两帧才看得出来，因为气动力影响的是加速度，加速度积分成速度、速度再积分成位置，中间隔着两层积分。再比如你发现姿态角在高频抖动，问题往往不在气动表，而在Propagate的积分步长和FlightControl的增益不匹配。

4.3 属性树：外部程序碰不到内部变量，只能走这扇门

JSBSim 的所有内部状态都注册在一棵属性树上，外部程序通过字符串名字读写，不直接访问成员变量。这个设计的好处是解耦：你改自己的飞控代码，不需要重新编译 JSBSim；坏处是所有交互都是字符串查找，写错名字不报错，只是读到 0。

属性名是分层级的，position/h-sl-ft是海拔高度（英尺），velocities/vc-kts是校准空速（节），attitude/pitch-rad是俯仰角（弧度），fcs/throttle-cmd-norm是归一化油门指令，fcs/elevator-cmd-norm是升降舵指令。前缀大致分几类：position、velocities、attitude、accelerations是状态量，fcs是飞控指令和舵面，propulsion是发动机，aero是气动中间量，simulation是时间、帧号这类元信息。

// 读：拿当前帧的迎角（弧度），用于外部监控 double alpha = fdm->GetPropertyValue("aero/alpha-rad"); // 写：把外部的升降舵指令塞进去，代替脚本里的常量 fdm->SetPropertyValue("fcs/elevator-cmd-norm", elevator_cmd); // 批量绑定：如果同一个属性每帧都要读，用节点指针避免重复的字符串查找 JSBSim::FGPropertyNode* node = fdm->GetPropertyManager()->GetNode("position/h-sl-ft"); double alt = node->getDoubleValue();

最后那种写法在实时仿真里很重要。GetPropertyValue每次都要在属性树里做一次字符串比较查找，单次开销不大，但一帧里读几十个属性、每秒跑一百二十帧，累积起来是实打实的性能损耗。把热路径上的属性名在初始化阶段解析成节点指针，之后直接取值，能省掉这部分开销。

属性名写错的排查方式：在示例程序里加一段遍历，把所有注册过的属性名打出来，对着找。

// 初始化阶段调用一次，把属性树导出成文本，方便对照 fdm->GetPropertyManager()->Tie("simulation/this-is-a-probe", &probe); fdm->GetPropertyManager()->Unbind(); // 清掉探针 std::string dump = fdm->GetPropertyManager()->GetPropertyCatalog(); printf("%s\n", dump.c_str());

这份目录动辄几千行，按前缀过滤一下再看，比盲猜快得多。

4.4 换一架飞机：XML 模型和 JS 脚本改哪里

想把自己的一架无人机塞进去跑，复制一个现成的飞机目录改名，然后改三个地方。第一处是metrics节点，翼面积、翼展、弦长、平尾面积和力臂、垂尾面积和力臂、气动参考点位置，这些是气动力的几何基准，单位统一用英尺或英寸，每个数值后面都要带unit属性，不带的话 JSBSim 按默认单位猜，猜错了整架飞机的力量级都不对。

<metrics> <wingarea unit="FT2"> 174.0 </wingarea> <wingspan unit="FT"> 35.8 </wingspan> <chord unit="FT"> 4.9 </chord> <htailarea unit="FT2"> 20.0 </htailarea> <htailarm unit="FT"> 14.5 </htailarm> <vtailarea unit="FT2"> 16.5 </vtailarea> <vtailarm unit="FT"> 14.0 </vtailarm> <!-- 气动参考点，一般是平均气动弦前缘的 25% 处 --> <location name="AERORP" unit="IN"> <x> 40.0 </x> <y> 0.0 </y> <z> 0.0 </z> </location> </metrics>

第二处是mass_balance里的空重和重心位置。重心位置直接决定静稳定裕度，重心太靠前飞机会低头、配平阻力大，太靠后会出现俯仰发散，也就是大家说的「尾沉」。改这组数的时候，建议先只改空重、不改重心，跑一遍看配平迎角有没有明显变化，再单独调重心。

第三处是气动表。aerodynamics下面按轴分LIFT、DRAG、SIDE、PITCH、ROLL、YAW，每个轴下面若干function，每个 function 是一个查表或者公式组合。新手最容易在这里犯的错是把实验数据的单位直接贴进去——风洞数据迎角是度，JSBSim 的alpha-deg属性也是度，但如果你引用了aero/alpha-rad又按度填表，出来的升力会小五十多倍，飞机根本抬不起头。

脚本层面，改飞机的气动之外还要看Systems目录。飞行控制系统的增益、限幅、滤波器参数都在那里，换了机型之后操纵响应会完全不同，原来调好的 PID 增益大概率要重调。我一般的做法是先把飞控系统整个旁路掉，用直接舵面指令跑几组阶跃响应，把气动模型本身验证完，再接回飞控闭环调增益。

5. 踩坑与排查：VS2015 下最容易翻车的五类问题

5.1 链接期报 LNK2005 和 LNK2019

现象是编译全过，链接阶段刷出一屏LNK2005: xxx 已经在 libcmt.lib 中定义，最后跟一个LNK1169: 找到一个或多个多重定义的符号。原因是运行库不匹配：某个工程用了/MT（静态 CRT），另一个用了/MD（动态 CRT），两套 CRT 的符号同时被拉进来。

解决方式是全解决方案统一。在 VS 里选中解决方案根节点，右键「属性」，确认「所有配置」和「所有平台」下「C/C++ → 代码生成 → 运行库」的取值一致。新建工程默认是/MDd，老工程可能被改成/MT，加进解决方案之后就冲突了。

LNK2019: 无法解析的外部符号是另一回事。如果未定义的符号带sgPath::、sg_debug、XMLDocument这类前缀，说明src/simgear下的源文件没被加进项目。把它们手动加进vcxproj的ClCompile列表，或者把整个目录按通配符包含进来。

5.2 运行时提示找不到飞机文件

现象是程序启动后控制台打印Could not open aircraft file: aircraft/xxx/xxx.xml，然后直接退出。三种原因，按概率从高到低排：工作目录不对、SetRootDir的路径层级不对、文件名大小写不对。

工作目录的问题最好查，VS 里「项目属性 → 调试 → 工作目录」默认是$(ProjectDir)，也就是.vcxproj文件所在目录。而数据目录通常在解决方案根目录下，中间差着几层。改成$(SolutionDir)或者数据根目录的相对路径即可。命令行运行时，先cd到输出目录再执行，不要让相对路径依赖当前 shell 的位置。

SetRootDir后面跟的路径要指到包含aircraft的那一层，不是aircraft本身。这一点在代码里看不出来，因为构造函数不校验，直到LoadModel去拼root/aircraft/name/name.xml才发现拼出来的路径不存在。

大小写这条在 Windows 上一般不发作，但如果你把工程拷到 Linux 或者用 WSL 跑，C172X和c172x是两个不同的目录，会直接崩在这里。

5.3 仿真跑起来之后数值发散

现象是前几秒正常，跑到十几秒时姿态角突然指数级增大，几十帧内变成NaN，然后整条曲线废掉。这类问题八成不在积分器，在气动表或者配平。

先查气动表的边界。tableData里的迎角范围如果只覆盖 -10 到 15 度，而仿真过程中迎角冲到了 20 度，超出范围的点 JSBSim 默认做线性外推，外推出来的升力系数可能是负的，于是飞机越低头、迎角越大、升力越负，正反馈发散。解决办法是把表的范围拓宽到 -20 到 25 度，或者定义一个clamp行为。

再查配平。用RunIC之后的第一帧看看各轴力矩是不是接近零。如果不是，说明初始条件给的配平量跟气动模型对不上，飞机一上来就在被一个恒定的力矩推着转。可以在脚本里给fcs/pitch-trim-cmd-norm一个小量做手动配平，也可以调FGInitialCondition的配平模式让它自动求解。

还有一种情况是积分步长太大。dt取 1/60 对某些高机动模型就不够，特征频率接近奈奎斯特频率时数值积分会不稳定。把dt减到 1/240 再跑一遍，如果抖动消失，就是步长问题。

5.4 输出 CSV 缺列或者时间戳不连续

缺列的原因是output节点里写的属性名拼错了。JSBSim 遇到不存在的属性不会报错，那一列就一直是 0 或者干脆不输出。对照GetPropertyCatalog()的导出一项一项核，别凭记忆写。

时间戳不连续是另一个信号。CSV 里的时间列如果是 0、0.05、0.10、0.20，中间少了 0.15，说明那一帧Run()返回了 false，输出通道虽然跑了但没有推进状态。往下查日志，通常是某个模型报了警告。如果 false 出现在脚本事件触发的那一帧附近，多半是事件里的set操作把某个属性设成了非法值，比如把归一化量设成了大于 1 的数。

5.5 Debug 能跑，Release 崩

这类问题最费时间。Debug 下初始化变量有 0xCC 填充，Release 下是未定义值，某个忘了初始化的成员变量就会在 Release 下变成随机数。常见的嫌疑是气动表里某个系数忘了给默认值，或者FGFDMExec的某个指针在构造后没判空就用了。

另一个常见原因是浮点优化。Release 默认开/O2，编译器会做浮点重排和 FMA 合并，某些本来靠运算顺序侥幸不溢出的表达式会溢出。如果确认逻辑没问题，试着在 Release 配置里把「浮点模型」改成/fp:precise，看问题是否消失。消失的话就要回来查那个表达式的数值范围，多半是量级悬殊的加减法导致的精度损失。

6. 二次开发：把 FDM 内核嵌进自己的程序

工程跑通之后，真正的价值在于把它当成一个库用起来，而不是当成一个独立 exe。我一般会做三步改造。

第一步，把主库编成静态库，在自己的项目里引用。这样不需要分发 DLL，也不用管运行库版本。代价是每次改 JSBSim 源码都要重新链接，但对于大多数飞控验证场景，源码基本不动，只改数据文件和自己的外层逻辑。

第二步，把属性树当成软总线。自己的飞控算法、地面站、视景程序都通过属性名读写，谁都不直接碰 JSBSim 的内部对象。外层的调度逻辑可以很简单：

// 每帧：自己的飞控算一次 -> 写指令进属性树 -> Run 一步 -> 读状态出来 while (running) { double roll_cmd = my_controller.GetRollCmd(); double pitch_cmd = my_controller.GetPitchCmd(); // 飞控输出映射到归一化舵面，限幅在 [-1, 1] fdm->SetPropertyValue("fcs/aileron-cmd-norm", clamp(roll_cmd, -1.0, 1.0)); fdm->SetPropertyValue("fcs/elevator-cmd-norm", clamp(pitch_cmd, -1.0, 1.0)); fdm->Run(); my_controller.Update( fdm->GetPropertyValue("position/h-sl-ft"), fdm->GetPropertyValue("velocities/vc-kts"), fdm->GetPropertyValue("attitude/phi-rad")); }

第三步，如果要加自己的力模型，比如螺旋桨滑流对机翼的干扰、地面效应的修正，用FGModel派生一个类，实现Run()，然后在FGFDMExec的模型链里插到指定位置。插入点的选择就是第 4 章那张顺序表的逻辑位置，气动修正要排在Aerodynamics->Run()之前，推进修正要排在Propulsion->Run()之后。

改造之后怎么验证。我固定看三个数：一是配平残差，同一初始条件下RunIC之后的三轴力矩应该接近零；二是能量守恒，无动力滑翔时总能量（动能加势能）的衰减应该平滑，出现台阶说明某一帧的力算错了；三是重复性，同一脚本跑两遍，CSV 逐帧对比应该完全一致，不一致说明有未初始化的状态或者变量，多半是隐性的踩坑。这套检查我吃过亏之后养成了习惯，每次改完气动表或者飞控增益，先跑一遍这三个数，再去看具体的响应曲线。

希望帮到你。

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