有段时间，我身边好几个朋友像是约好了一样，同时在跑自己的第一条 Demo。有人想做 WebRTC 的音视频传输示例，对着视频教程把信令服务器搭起来，结果本地画面死活出不来；有人刚拿到一块 GD32F470 开发板，想把 FreeRTOS 官方例程点起来，却在驱动安装和调试器配置那一步卡了一整个晚上；还有人在 Android 工程里折腾 AIDL 跨进程通信，照着博客代码抄了一遍，编译通过了，但服务就是连不上。
这些事放到短视频里，通常只需要一个镜头：UP主拉好代码，敲几行命令，屏幕亮起来，然后说一句“这样就跑通了”。但真正上手的人会立刻发现，自己面临的不是那几十行示例代码，而是代码之外的一堆细节：路径对不对、SDK 版本是不是和教程一致、权限有没有放开、端口是不是被占、依赖库有没有装全、日志到底该看哪一行。
所以我越来越认可一个判断：跑通一条 Demo，真正练的不是“照着做”，而是“处理不确定性”。教程给你的是路径，但路径上的每一个岔路口，都得靠你自己判断。能把一条 Demo 从“看起来能跑”带到“我清楚每一步为什么能跑”，这个过程中收获的东西，远远超过 Demo 本身。
1. 先搞清楚“跑通 Demo”这件事到底在练什么
1.1 教程里看不见的变量，才是真正的坎
几乎所有视频教程都有这样一句话：先把环境配好。但环境恰恰是最容易让人栽跟头的部分。UP主录制视频时，用的可能是特定版本的操作系统、特定版本的 SDK、特定版本的第三方库。你在自己电脑上执行同样步骤，只要有任何一项版本不一致，结果就可能完全不同。
拿 Android AIDL 举例。不同版本的 Android Gradle Plugin 对 AIDL 文件的目录要求是不太一样的。旧教程里可能让你把.aidl文件放在src/main/java目录下，再用sourceSets指定路径；新工程默认则是放在src/main/aidl下面。如果你拿到一个比较老的教学代码，直接往新工程里复制，编译大概率会报找不到接口类的错误。就这么一个配置差异，足以让完全不懂 Gradle 的新手原地放弃。
WebRTC 类的 Demo 更明显。浏览器对摄像头和麦克风的权限策略、信令服务器地址、ICE 服务器配置，任何一个环节和教程对不上，结果都是同一个：画面出不来。很多人在这一步反复重装依赖、重开项目，但问题根本不在代码里。因为视频出来之前，已经过了getUserMedia→RTCPeerConnection→ 信令交换 → ICE 候选收集 → 渲染显示这么多层，每一层都是一个独立的出错点。
嵌入式领域就更加直接。EtherCAT 主站的驱动安装、GD32F470 的时钟树配置、INA228 这类传感器 demo 板的 I2C 地址设置，全都高度依赖具体的芯片型号、硬件版本和数据手册。同一份示例代码，换一块板子、换一颗传感器、换一根接线，行为都可能完全不一样。
所以，跑 Demo 的第一步，不是急着复制代码，而是先摸清自己当前环境的“底数”。操作系统版本、编译器版本、SDK 版本、依赖库版本、硬件型号、通信接口方式，这些都构成了你排查问题时的坐标系。没有这个坐标系，出了问题你只能靠猜。
1.2 Demo 不是终点，而是一段最小可验证链路
很多人跑通一个 Demo 之后，觉得“我学会了”，然后关掉项目。这个习惯有点可惜。Demo 的价值不在于最后那个闪过的画面，而在于它把一条技术链路压缩到了最短可运行的程度。
比如一个 WebRTC Demo，最终表现是“视频通了”。但为了这个结果，你需要打通媒体设备访问、信令服务器通信、点对点连接建立、音视频编解码、渲染显示这一整条链路。一个 AIDL Demo，表面上是“跨进程调用拿到了一个字符串”，但背后涉及 Service 生命周期、Binder 机制、AIDL 文件生成、客户端绑定流程、跨进程数据序列化。任何一个环节理解不到位，后面换个场景就可能出问题。
这也是为什么我更建议，在 Demo 跑通之后，立刻做一件很小的事：改动一个参数，观察结果是否跟着变。比如改一个端口号，AIDL 服务是否仍然能连通；换一张图片、换一段文字，分页排版结果是否合理；调一个任务优先级，FreeRTOS 的行为是否改变。
这个“改一点、看一点”的步骤，才是把“教程的 Demo”变成“你自己的经验”的关键。它能确认你运行的代码里，哪些参数是真正的因果变量，哪些只是摆设。
2. 跑 Demo 之前，先花十分钟确认七件事
跑一条新的 Demo，不管是哪一类技术，我会先做一个十分钟的前置检查。这个检查解决的不是“代码能不能编译”，而是“我的环境是否满足这个 Demo 运行的前提假设”。它通常能省掉后面半小时甚至更久的调试时间。
2.1 工具链和依赖：先确认手里拿的是不是能用的工具
第一件事，不看教程，先看你自己的工具链。
- Python 项目：确认
python --version、pip --version，以及是否应该使用虚拟环境。 - Android 项目：确认
adb devices能识别设备，SDK 路径已配置，Gradle 能正常拉取依赖。 - 前端项目：确认
node --version、npm --version，以及系统 PATH 环境变量里有没有缺失项。 - 嵌入式项目：确认交叉编译工具链、调试器、烧写工具都已安装，比如
arm-none-eabi-gcc --version、openocd --version。
这一步看起来基础，但作用很大。工具链缺失、版本过老、路径没加入环境变量，这些都会让后面每一步报出看似毫无关联的错误。而且这类错误有欺骗性：你以为是项目代码的问题，反复检查代码，最后才发现是编译器本身不工作。
2.2 输入、输出和日志：先想清楚这个 Demo 吃了什么、吐出什么
每个 Demo 都有固定的输入和输出。输入可能是一个文件路径、一个 URL、一个端口号、一个 I2C 地址，也可能是一份需要按特定格式排列的数据。跑之前，最好先问自己几个问题：
- 这个 Demo 的入口在哪里？
- 运行时需要提供哪些参数？参数是写在配置文件里，还是写在命令行里？
- 参数不合法时，它是立即报错，还是会静默失败？
- 输出在哪里？是控制台日志、日志文件、界面显示，还是硬件上的某一个现象？
带着这几个问题去读示例代码，比直接点击运行有效得多。因为一旦结果不符合预期，你至少知道该去哪一层找原因。
还需要确认日志的位置。很多 Demo 默认把日志输出到标准输出，但有的会写进指定文件，有的只有 Debug 版本才打印。如果找不到日志，排查就无从下手。
2.3 权限、端口和资源：最容易被忽略的隐形变量
权限问题是所有 Demo 里最常见的隐形坑。
- 串口设备需要访问权限，否则输出可能完全为空。
- 摄像头、麦克风需要浏览器或系统授权，否则 WebRTC 本地画面就出不出现。
- Android 应用需要动态申请权限，很多 Demo 代码里没有完善的权限处理，需要你自己补上。
- Linux 下访问硬件设备，可能需要普通用户加入
dialout组或使用sudo，而不同发行版的表现又不一样。
端口和资源也一样。WebRTC 的信令服务器如果起了 8080 端口，但你本机已经有一个服务占用 8080，程序并不会帮你换端口，可能只是报一个含糊的“连接失败”或者干脆卡住。嵌入式开发板如果供电不足，程序刚下载进去能运行，跑一会儿就复位，这种问题如果不知道硬件边界，会浪费大量时间。
所以，前置检查的重点是确认四个字：前提成立。工具能跑、输入有准备、输出有位置、权限和资源都正常。做完这十分钟，你才不是在碰运气。
3. 几种热门 Demo 的跑通思路
不同领域的 Demo，难点不一样。下面按照目前比较常见的类型，梳理一下各自的跑通思路和验证方法。这些都不是官方步骤，而是通用的处理框架，具体参数要以你当前项目为准。
3.1 WebRTC demo：先跑本地回环，再跑双端通信
WebRTC 的 Demo 最容易出现“看起来全对，但画面就是出不来”。问题通常集中在权限、信令和网络三个环节。
建议先跑本地回环测试，也就是同一个页面里，用本地媒体流同时充当发送端和接收端。这一步如果成功，说明摄像头/麦克风权限、浏览器媒体采集都是正常的，问题范围就缩小到了信令和网络层。本地回环正常后，再用两台设备测试。两台设备之间如果失败，就依次检查信令服务器地址、ICE 服务器配置、端口连通性和防火墙策略。
跑通之后，重点确认三份日志：getUserMedia是否返回了 MediaStream、RTCPeerConnection是否进入了连接状态、ICE 候选是否收集完成。这三份日志能帮你定位问题出在采集、连接还是传输阶段。
3.2 Android AIDL demo：先确认 Service 真的被绑定
AIDL 的 Demo 链路不长，但每一步都必须成立。
首先，AIDL 文件的包名必须和生成接口的包名一致，文件放置在标准目录，否则客户端根本找不到接口类。其次，Service 必须在 AndroidManifest 中注册，并明确它运行在哪个进程。最后，客户端要在onServiceConnected回调里拿到 Binder 代理，再调用接口方法。
遇到“服务连不上”的问题，不要急着搜代码。先把日志分成几段看：Service 的onCreate有没有被调用？onBind有没有执行？bindService有没有回调？等到onServiceConnected触发之后，再往下追。跨进程通信最忌讳跨过一个关键节点直接猜测结果，因为中间断掉任何一环，后面的代码都不会执行。
3.3 iOS 文字分页排版 demo：把排版过程拆成计算和绘制
“UI 文字分页排版”看起来是渲染问题，实际上是计算问题。同一段文字在不同宽度、字体、行高、字重下，计算出的高度有很大差异。再加上可能存在状态栏、导航栏、安全区域这些可用区域的变化，分页结果就更容易失控。
我的做法是，先不追求最终效果，先把中间计算值打出来：文字总高度、行高、分页数量、当前页可绘制范围。确认这些数值符合预期之后，再去检查渲染结果。如果渲染不对，但中间值没问题，问题大概率在绘制坐标或自动布局约束上；如果中间值就不对，那就要回到字号、行高、控件宽度这层去检查。
3.4 嵌入式类 demo：先确认硬件边界，再谈软件逻辑
嵌入式类是环境变量最多的场景。EtherCAT 驱动安装、GD32F470 的 FreeRTOS 例程、INA228 demo 板，这些项目有一个共同点：硬件接线、芯片型号、驱动版本、寄存器配置都会影响结果。
如果拿到的是硬件厂商提供的原厂 demo 程序，比如打印模块或扫码模块的演示工具，也要先把硬件连接方式、驱动版本和固件版本确认好再启动。厂商 demo 往往预设了特定的通信协议和设备地址，如果你的设备版本和演示版本不一致，即使程序正常启动，也得不到预期结果。
嵌入式 Demo 的调试顺序，建议是先确认硬件是否到达预期状态，再进入软件调试。先看供电是否正常、通信接口是否连通、设备是否被系统识别，再去看编译和日志。在硬件状态未知的情况下，直接读代码、改参数，很容易走偏。
3.5 当程序进入“Demo 模式”，先别急着重装
还有一种比较特殊的情况：程序本身运行正常，但界面或标题栏出现了“Demo”字样。比如一款数据分析软件明明在用，却显示成了演示模式；又或者某个硬件厂商提供的 demo 工具，连不上设备时停在演示界面。遇到这种事，第一反应通常是想重装软件或删配置文件，但这个方向往往不对。
更合理的排查路径是：先去检查许可证状态、授权文件、试用期信息，再确认软件是否能正常识别硬件设备。很多“Demo 状态”，其实是许可证过期、设备未连接、加密狗没识别到，或者激活信息保存在某个被改动过的环境变量里。先把这些可查项过一遍，而不是重装，才不会把问题覆盖成更难排查的现象。
3.6 用 Codex 或 AI 辅助生成 demo：生成不是终点，验证才是
用 AI 辅助生成 Demo 是现在很常见的方式。Codex 这类工具可以快速产出一份能跑的代码，但它的输出仍然需要你自己校验。
我有一个习惯：把需求先拆成输入、处理、输出三部分，再让 AI 生成对应的最小版本。生成之后，不直接拿完整结果往工程里塞，而是先跑最核心的一个函数，确认输入输出符合预期。因为 AI 生成的代码可能引用了过时 API、和当前依赖版本不兼容，或者和你的工程架构不匹配。它真正的价值是帮你快速获得一个待验证的初版，而不是帮你绕开调试这件事。
4. 复制粘贴跑不通时，按这个顺序排查
不管跟着谁跑，Demo 跑不通都是常态。真正拉开差距的，是从“跑不通”走到“跑通了”这个过程里，你怎么组织自己的排查顺序。
4.1 先给现象分类：报错、卡住、静默失败
不同的现象要采用不同的排查起点。
如果是报错，相对好办，因为报错信息通常给了明确方向。但要注意，报错信息有时候会误导你。比如某些构建工具报“找不到符号”，真正原因可能是依赖没有拉取，而不是代码里少了一个类。所以，报错要结合完整堆栈和上下文日志一起看。
如果是卡住，说明程序在某一步等待资源或等待响应。这时候先看它的状态：是 CPU 高占用还是完全无响应？是日志还在刷但没有进展，还是连日志都不输出？这能帮助你区分死循环、网络等待和资源竞争。
最麻烦的是静默失败：编译通过、命令执行完、日志没有任何异常，但结果就是不对。这种情况多半是某个输入条件不满足预期，但程序没有做校验。破解办法是拆点验证：在关键节点插入日志或打印语句，一步步看数据从哪里开始偏离。这种能力基本靠练，练多了就会形成肌肉记忆。
4.2 逐层排查：输入、环境、参数、工具边界
我在排查时用的顺序大致是下面这四层。每一层都配一个最小的验证点，不要在某一层里死磕。
第一层，看输入。路径是否存在、参数格式是否正确、字段类型是否匹配、文件编码是否混乱、URL 是否可达、端口是否可连通。很多 Demo 跑不通，就是因为输入和一个隐含假设不一致。
第二层，看环境。依赖版本是不是和示例代码匹配、SDK 版本是否兼容、系统库是否缺失、网络策略是否阻挡、权限是否授予。最有效的验证方式是新建一个空工程或空脚本，只调用 Demo 里最关键的一个依赖，看它能不能跑。如果最小依赖都跑不起来，问题就在环境层。
第三层，看参数。并发数、超时时间、分辨率、缓冲区大小、堆栈大小、优先级，这些配置类问题通常不会导致编译失败，但会严重影响运行结果。嵌入式里最典型的就是 FreeRTOS 任务堆栈设置太小，任务一运行就栈溢出，表现出来的现象是随机复位或者行为错乱。
第四层，看工具边界。示例代码是否已经过时、第三方库是否改了 API、当前平台是否对特定功能有限制。这一步通常需要去查对应版本的文档和更新日志，不要死磕旧代码。
4.3 一次实际操作中的排查记录
举一个我印象比较深的例子。有一次我跑一个 Android AIDL 示例，客户端一直提示 Service not connected。
我先做第一层排查：确认客户端调用了bindService，包名没有问题，Service 已经注册在 AndroidManifest 里。看起来都正常。
然后做第二层，看环境：打开 logcat，过滤 Service 相关的日志，发现onCreate被调用了，但onBind返回了 null。到这一步，问题已经缩小到“Service 绑定实现”这一层。
继续读代码，发现我在 Service 里写的 Binder 对象，没有继承 AIDL 生成的 Stub 类。也就是说，客户端拿到的不是跨进程通信的代理对象，而是一个普通的本地对象。修正之后，客户端立刻收到了回调。
回过头看，整个过程里真正有价值的部分，不是最后那一行修复，而是我用日志一步步把问题范围从整个 App 收缩到onBind方法。这就是分层排查的意义。如果一开始就凭感觉去改 Service 注册配置，很可能反向工作。
5. 跑完 Demo 后，接下来做什么
第一条 Demo 跑通后，不同的人会进入两种极端状态：一种觉得自己已经会了，另一种觉得“这不过是在抄作业，没有意义”。这两种判断都不太准确。跑通 Demo 的价值，取决于你接下来怎么对待这条链路。
5.1 先做最小修改，把别人的链路变成自己的
最有效的下一步，不是马上开始跑第二个 Demo，而是先对第一个 Demo 做最小修改。改一个参数、换一个输入、加一个字段、加一行日志，然后观察结果的变化。
这一步不需要多大难度，但它能帮你慢慢建立因果感。比如你改了信令服务器地址，WebRTC 连接行为是否变化；你在 AIDL 接口里加了一个新方法，客户端是否能正确调用；你把排版 Demo 里的字号改大，分页数量是否跟着改变。这些看起来琐碎的动作，恰恰是“能运行别人代码的人”变成“能理解这条链路的人”的分水岭。
5.2 把踩过的坑记成清单，而不是靠记忆
跑 Demo 时踩过的坑，是很宝贵的经验。建议用 Markdown 或普通笔记把它记下来，内容包括：环境信息、原始报错、排查步骤、最终解决方案、消耗时长。
记录的价值在时间沉淀之后才会体现。下次遇到类似场景，你不需要重新搜索，直接翻清单。而当你的清单积累了二三十条之后，你会发现很多问题的共性是“输入不符合隐含假设”或“环境版本不一致”。这些共性认知，会帮助你在开启新项目时提前规避一大批坑。
5.3 从“跑通别人的 Demo”到“做出自己的 Demo”
如果你想让 Demo 变成自己真正能使用的东西，可以遵循这个顺序：先跑通，再优化，最后工程化。
先跑通，指的是确认最小链路完整，输入输出符合预期。这个阶段不追求性能，也不做边界处理，目标是拿到确定性的结果。
再优化，是在跑通的基础上补充常见的边界条件。比如并发请求、异常输入、网络波动、资源限制，给关键路径加上错误捕获和重试逻辑。
最后工程化，是加入版本管理、日志记录、参数配置化、自动化测试和部署流程。每一步需要做到什么程度，取决于你的目标。如果只是学习验证，前两步就够了；如果要放进生产环境，第三步不能跳过。
跑 Demo 的终点，不是那个成功的输出，而是你形成了一条可复用的“输入-验证-修正-沉淀”路径。当你完整走过三五次这样的循环，新项目来临时，你会自然地先做最小验证，先查输入，再看环境，再调参数，直到把链路打通。那时候，你看教程的方式也会发生改变——你不再只关心 UP主点了哪个按钮，而是会去想，他在哪个节点做了判断，哪些步骤依赖特定条件，哪些地方换一个环境就会失效。
这大概就是“跟着 UP 主跑通第一条 Demo”的真正意义：你不是在复制一个结果，而是在学习一套面对不确定性的行动方式。
