跑通任意技术Demo的通用方法论：环境、依赖与日志排查实战

跟着视频教程学习技术最让人崩溃的场景不是代码复杂而是“照着一行行敲完结果跑不起来”。你检查了一遍又一遍发现和教程里一模一样但别人几分钟点亮屏幕你却卡在报错里半小时起步。更难受的是你不知道该从哪里查起。这不是你一个人的问题。把大量时间耗费在“跑通第一个 Demo”上是很多入门开发者最常见的挫败来源。但这里有一个值得先说清楚的判断绝大多数 Demo 跑不通不是代码问题而是环境、版本、依赖、权限和验证方式的问题。换句话说它不是“会不会写代码”的能力问题而是“是否掌握一套可复用的运行方法”的方法论问题。这篇文章会用一套通用思路带你拆解跑通任意技术 Demo 的完整链路并用 Android AIDL、WebRTC、嵌入式 FreeRTOS 三个真实场景做演示。读完你会明白为什么有人总能很快跑通别人的项目以及下次拿到一个新 Demo 时你应该按什么顺序操作。1. 为什么你总是卡在“跑通 Demo”这一步先来还原一个典型场景。你找到一个教程作者在视频开头说“环境我已经装好了我们直接开始”。然后他创建项目、添加依赖、写代码、点击运行一切顺利。你跟着做到第三步Gradle 开始下载依赖等了十分钟最后报了一个看不懂的错误。这时候你会下意识怀疑自己是不是漏了什么步骤是不是代码敲错了是不是这个教程不适合我大多数情况下你的怀疑是错的。Demo 跑不起来的真实原因往往会落在下面这几个层面报错类型典型症状实际出问题的层面环境类找不到 SDK、JDK 版本不对、Python 命令不存在本机环境与项目要求不匹配依赖类Maven/Gradle/npm 依赖下载失败、版本冲突依赖解析与网络环境编译类找不到符号、包不存在、Build Tools 版本错误项目配置与工具链版本运行时类端口被占用、连接被拒绝、权限不足系统配置和服务状态验证类程序启动了但不知道是否正常缺少明确的成功标准一个 Demo 能跑通本质上是走完了下面这条链路环境匹配 - 依赖就绪 - 编译通过 - 启动成功 - 结果可验证这五个环节中只要有一个断了Demo 就“跑不通”。但新手通常只会盯着“编译通过”这一环看认为代码对了一切就对了。事实是编译通过只意味着语法和类型没问题它不代表运行环境正确更不代表你的验证方式正确。这里有个很容易被忽略的细节教程类内容通常把环境准备一笔带过因为作者已经提前装好了。但环境才是最容易出问题的一环。你的 JDK 版本和他不同你的 Docker 没启动你的端口已经被别的服务占用——这些都不可能通过“重写一遍代码”来修复。所以跑通 Demo 的起点不是代码而是环境。理解了这一点你会省下大量无意义的自我怀疑。2. 先搞懂 Demo 的几种类型在动手之前建议你先判断一下手里的 Demo 属于哪一种。不同类型的技术 Demo卡点和排错策略完全不同。把它们混为一谈是效率低下的重要原因。Demo 类型典型场景最常见的卡点排错重心教程演示型跟着视频敲一段 Python/Java 示例本机 Python/JDK 版本版本匹配、依赖安装API 接入型接入地图、支付、AI 接口密钥无效、参数错误鉴权配置、请求参数框架集成型Spring Boot Redis、Docker 部署配置项缺失、端口冲突配置文件、依赖关系系统级应用型Android AIDL、iOS 分页排版SDK 版本、权限、真机/模拟器差异工具链、权限声明网络通信型WebRTC、WebSocket、联机应用信令不通、NAT 穿透失败网络连通性、协议流程嵌入式硬件型FreeRTOS、EtherCAT 驱动安装、GD32 开发板工具链、烧录、驱动安装编译链、串口、硬件连接为什么强调先分类因为不同类型的 Demo判断成功的标准并不一样。教程演示型Demo的成功标准是“控制台输出了预期内容”API接入型是“接口返回了正确数据”网络通信型是“两个端建立了连接并能互相传数据”嵌入式硬件型则是“开发板上的现象与预期一致”。如果你用“控制台有没有输出”去衡量一个网络通信型 Demo那么两端没连上你根本看不出来。更实际的意义在于分类能帮你快速定位问题属于哪一层。Android AIDL 卡了九成是 SDK 版本、Service 注册或进程通信权限的问题和你的 Java 基础无关WebRTC 卡了八成是信令流程没有走通而不是摄像头打不开。所以拿到任何 Demo第一件事不是跑而是判断这是一个什么类型的 Demo它跑通的“成功标志”是什么它的卡点大概率会在哪个层这三个问题想清楚你已经有了一半的把握。3. 环境准备用隔离方式代替“一把梭”跑 Demo 前最危险的念头是“我按教程装一遍最新版本就行”。最新的不一定能用全局安装的不同项目还会互相污染。比如你同时跑一个需要 Node 16 的老项目和需要 Node 20 的新项目只靠全局 Node 版本肯定要做很多切换工作。务实的做法是给每个 Demo 一个隔离的环境。下面三条路径覆盖了最常见的几种情况。3.1 Python 项目用虚拟环境无论项目要求 Python 3.8 还是 3.11都推荐先建虚拟环境再装依赖。这不是多余的仪式感而是避免把全局 Python 环境搞乱的关键动作。# 创建虚拟环境venv 名称自定义 python3 -m venv .venv # 激活虚拟环境Windows 使用 .venv\Scripts\activate source .venv/bin/activate # 安装项目依赖 pip install -r requirements.txt # 确认当前 Python 路径 which python激活后pip install装的包只会进入这个虚拟环境。跑完不需要时直接删除.venv目录即可对系统没有残留影响。3.2 Node 项目用版本管理器Node 不同大版本的行为差异很大推荐用 nvmmacOS/Linux管理多个版本而不是直接装一个全局版本一用到底。# 安装指定版本 nvm install 20 # 切换版本 nvm use 20 # 确认版本 node -v判断一个 Node 项目的版本要求先看项目根目录有没有.nvmrc文件或engines字段再看 README。如果都没有看看 package.json 里 lock 文件格式也能推断出大概的 npm 版本区间。3.3 带中间件依赖的项目用 Docker很多 Demo 需要 MySQL、Redis、Kafka 等中间件。在自己机器上一个个安装并配置启动既慢又容易污染环境。用 Docker 起一个一次性容器是最省事的隔离方式。# 运行一个临时 MySQL 8 容器端口映射到 3306 docker run -d \ --name demo-mysql \ -p 3306:3306 \ -e MYSQL_ROOT_PASSWORD123456 \ mysql:8需要注意3306 端口如果已被本机 MySQL 占用容器会启动失败。这时先执行docker ps -a查看容器状态再用docker logs demo-mysql看日志。端口冲突时把-p 3306:3306改成-p 3307:3306并在项目配置里把数据库端口改成 3307。3.4 一个最容易被忽略的细节镜像源下载依赖超时是新手跑 Demo 失败的高频原因尤其是 Maven、Gradle、npm 从国外源拉取依赖时特别不稳定。这类问题不是环境坏了是网络路径太长。包管理器国内镜像配置方式npm在项目根目录创建.npmrc写入registryhttps://registry.npmmirror.comMaven修改settings.xml中的 mirror 地址Gradle在build.gradle中把repositories改为阿里云镜像pip执行pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple注意这不是绕过什么限制只是把软件包的下载地址换成延迟更低的镜像源属于常规工程操作。4. 跑通任意 Demo 的通用四步法有了环境隔离的意识下面这套通用流程可以应对绝大多数 Demo。4.1 第一步先读 README锁定前置条件不要一上来就 clone 代码然后点运行。先用三分钟扫一遍 README找到这些信息运行环境操作系统、JDK/Node/Python 版本依赖服务是否需要 MySQL、Redis、Docker启动命令npm start、mvn spring-boot:run、make run配置文件是否需要环境变量、密钥、数据库连接串判断一个 README 是否“完整”有个简单的标准照着 README 的命令从头执行一遍任何一个步骤出现 README 没提到的报错都说明它有疏漏。很多开源项目的文档写得不够好需要你结合 Issue 区和评论区补充判断。4.2 第二步最小化运行砍掉非核心功能很多 Demo 为了方便展示把一堆功能塞在一起。常见的如“登录 列表 消息推送 缓存 二维码”。这些功能对演示来说很炫但每一个都是一条可能出错的链路。第一次跑通的目标只有一个把最小主链路跑通。其余功能一律先绕开或注释掉。什么叫最小主链路就是“项目说明里最重要的那个功能”。比如 AIDL Demo 的最小链路是“客户端能调用远程接口拿到返回值”WebRTC Demo 的最小链路是“两个页面能建立连接并看到对方画面”嵌入式 Demo 的最小链路是“开发板能启动调度器并输出日志”。如果你拿到一个 Demo 后第一反应是“我要把每个功能都跑一遍”那失败率会成倍增加。先把最小的跑通再逐步加功能两边对比出问题才知道是新增的部分导致的。4.3 第三步日志驱动定位问题运行失败后不要凭感觉改配置也不要反复重试。日志是最客观的证据。不同技术栈的日志查看方式不同但思路一致找到第一条报错而不是最后一条。例如# 查看 Node 服务日志 node server.js # 查看 Docker 容器日志 docker logs -f container-name # 查看 Android 应用日志 adb logcat -s AIDL_Demo:I *:S # 查看系统服务状态 systemctl status ethercat看日志时有几个原则第一从最早出现的报错开始定位。很多后续报错只是连锁反应真正的问题在最前面。第二只关注和你有关的那条报错。大型框架的日志会把无关警告和错误混在一起你需要根据类名、模块名、端口号等信息过滤。第三在写日志排查求助帖时把第一条报错原文贴出来不要只截图最后三行。这能帮助别人以及搜索引擎更快帮你定位。4.4 第四步验证结果并固化方案跑通后不要着急进入下一个阶段先用标准动作确认“它不是碰巧能跑”重启一次服务看能否再次成功清掉缓存目录重新执行一遍安装和启动命令用明确的命令验证输出例如curl接口、adb logcat过滤、串口工具接收确认能复现后把整个过程记录成文档或脚本。这一步很多人会跳过但它是从“我跑通了一次”到“我能稳定复现”的关键转化。改成脚本后下次换个机器或过三个月再跑可以节省大量重新梳理的时间。5. 案例一Android AIDL Demo 从创建到跑通现在用实际案例演示上面的方法论。先说 AIDL 解决了什么问题。Android 系统为了避免不同应用的进程互相干扰给每个应用分配了独立进程和独立内存空间。两个进程之间的数据不能直接共享需要通过 Binder 机制完成跨进程通信。AIDL 就是 Android 提供的接口定义语言用来规范“跨进程能调用哪些方法、传什么参数、返回什么结果”。5.1 环境准备跑 AIDL Demo 不需要特殊硬件只需要Android Studio版本以你安装的稳定版为准本文不指定具体版本号一个 Android 模拟器或真机JDK 17 或更高版本以 Android Studio 配套要求为准项目创建后确认项目的build.gradle中compileSdk和minSdk配置合理即可。5.2 创建 AIDL 接口文件在项目的app/src/main/aidl目录下创建 AIDL 文件。包名要和项目包名保持一致。文件路径app/src/main/aidl/com/example/demo/IMessageService.aidl// IMessageService.aidl package com.example.demo; interface IMessageService { String getMessage(String input); }这里定义了一个跨进程方法客户端传入一个字符串服务端返回另一个字符串。保存文件后Android Studio 会自动生成对应的 Binder 相关类。一个新手很容易踩的坑是修改 AIDL 文件后没有执行 Build运行时报找不到生成的类。修改 AIDL 后一定要执行一次Build Rebuild Project让编译器重新生成代码。5.3 实现服务端 Service创建一个 Service在onBind中返回 AIDL 接口的 Binder 对象。文件路径app/src/main/java/com/example/demo/MessageService.javapackage com.example.demo; import android.app.Service; import android.content.Intent; import android.os.IBinder; import android.os.RemoteException; import android.util.Log; public class MessageService extends Service { private static final String TAG AIDL_Demo; private final IMessageService.Stub binder new IMessageService.Stub() { Override public String getMessage(String input) throws RemoteException { String result Hello from AIDL: input; Log.d(TAG, result); return result; } }; Override public IBinder onBind(Intent intent) { return binder; } }关键点在于IMessageService.Stub它是编译器根据 AIDL 文件自动生成的抽象类服务端只需要继承它并实现方法即可。这里的方法运行在服务端进程返回值会通过 Binder 传递回客户端进程。5.4 注册 Service 并在客户端绑定在AndroidManifest.xml中注册 Service。Android 12 及以上要求显式声明android:exported。application ... service android:name.MessageService android:exportedfalse / /application然后在 MainActivity 中绑定服务。文件路径app/src/main/java/com/example/demo/MainActivity.javapackage com.example.demo; import android.content.ComponentName; import android.content.Context; import android.content.Intent; import android.content.ServiceConnection; import android.os.Bundle; import android.os.IBinder; import android.os.RemoteException; import android.util.Log; import android.widget.Toast; import androidx.appcompat.app.AppCompatActivity; public class MainActivity extends AppCompatActivity { private static final String TAG AIDL_Demo; private final ServiceConnection connection new ServiceConnection() { Override public void onServiceConnected(ComponentName name, IBinder service) { IMessageService messageService IMessageService.Stub.asInterface(service); try { String result messageService.getMessage(CSDN Demo); Log.d(TAG, 客户端收到: result); Toast.makeText(MainActivity.this, result, Toast.LENGTH_SHORT).show(); } catch (RemoteException e) { Log.e(TAG, 调用失败, e); } } Override public void onServiceDisconnected(ComponentName name) { Log.d(TAG, 服务连接断开); } }; Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); Intent intent new Intent(this, MessageService.class); boolean bound bindService(intent, connection, Context.BIND_AUTO_CREATE); Log.d(TAG, bindService 结果: bound); } Override protected void onDestroy() { super.onDestroy(); unbindService(connection); } }bindService的第三个参数Context.BIND_AUTO_CREATE表示如果 Service 还没创建系统会先创建它再绑定。如果onCreate里打印的bound为 false说明绑定没有成功需要先检查 Service 是否在 Manifest 中注册。5.5 运行验证与坑位提醒运行 App在 Logcat 中过滤AIDL_Demo预期能看到AIDL_Demo: bindService 结果: true AIDL_Demo: Hello from AIDL: CSDN Demo AIDL_Demo: 客户端收到: Hello from AIDL: CSDN Demo新手在 AIDL Demo 上容易踩的坑集中在三个地方第一AIDL 文件包名和项目包名不一致导致生成类导入失败。解决方式是保持包名统一。第二修改 AIDL 后没有 Rebuild运行时报找不到IMessageService。解决方式是执行 Build 让编译器生成最新代码。第三绑定失败且bound为 false。先确认 Manifest 中有 Service 声明再确认应用进程和 Service 进程是否匹配。如果 Service 配置了android:process客户端 bind 时要注意进程差异。一个小提醒如果你的 Demo 把 Service 放在独立进程想要客户端能绑定它Service 的android:exported通常要设为 true 或配置权限否则跨应用绑定会被拒绝。这取决于你的具体场景不是必须改。6. 案例二WebRTC 一对一通话 Demo 跑通WebRTC 是浏览器实时音视频通信的标准方案很多人在跑 WebRTC Demo 时发现它比想象中复杂。原因是它不是一个简单的“拉起摄像头”的 API而是包含三条完整链路媒体采集、信令交换、媒体协商与连接建立。其中最容易让新手困惑的是信令。WebRTC 本身不定义信令协议需要自己用 WebSocket 等方式交换 SDP 和 ICE 候选信息。这也是很多“照着抄都跑不通”的场景来源。6.1 环境准备这个 Demo 只需要 Node.js 环境和一个现代浏览器Chrome/Edge。mkdir webrtc-demo cd webrtc-demo npm init -y npm install wsws是 Node 的 WebSocket 库用于实现信令服务器。6.2 编写信令服务器文件路径server.jsconst WebSocket require(ws); const wss new WebSocket.Server({ port: 8080 }); const clients new Map(); wss.on(connection, (ws) { const id Math.random().toString(36).slice(2, 8); clients.set(id, ws); ws.send(JSON.stringify({ type: id, id })); ws.on(message, (message) { const data JSON.parse(message); const target clients.get(data.to); if (target) { target.send(JSON.stringify({ ...data, from: id })); } }); ws.on(close, () { clients.delete(id); }); }); console.log(信令服务器已启动ws://localhost:8080);这个服务器做的事情很简单每个连接进来时分配一个唯一 ID并转发两个客户端之间的消息。它不解析 SDP 内容只负责把一个客户端发给另一个客户端的 JSON 消息原样转发这是信令服务器的典型最小实现。6.3 编写前端页面文件路径index.html!DOCTYPE html html head meta charsetutf-8 titleWebRTC 一对一同款 Demo/title /head body video idlocal autoplay muted playsinline stylewidth:300px;border:1px solid #ccc/video video idremote autoplay playsinline stylewidth:300px;border:1px solid #ccc/video br / div我的 IDspan idmy-id等待分配.../span/div input idtarget-id placeholder输入对方 ID / button onclickstartCall()发起通话/button script const localVideo document.getElementById(local); const remoteVideo document.getElementById(remote); const myIdSpan document.getElementById(my-id); const targetInput document.getElementById(target-id); const pc new RTCPeerConnection({ iceServers: [{ urls: stun:stun.l.google.com:19302 }] }); const ws new WebSocket(ws://localhost:8080); let targetId null; // 获取本地摄像头/麦克风 navigator.mediaDevices.getUserMedia({ video: true, audio: true }).then(stream { localVideo.srcObject stream; stream.getTracks().forEach(track pc.addTrack(track, stream)); }).catch(err { console.error(获取媒体失败请确认浏览器已授权摄像头与麦克风, err); }); // 本地 ICE 候选信息通过信令发送给对方 pc.onicecandidate event { if (event.candidate) { send({ type: candidate, candidate: event.candidate }); } }; // 收到对方媒体流后显示到 remote 视频标签 pc.ontrack event { remoteVideo.srcObject event.streams[0]; }; function send(data) { if (targetId) { ws.send(JSON.stringify({ ...data, to: targetId })); } } ws.onmessage async event { const data JSON.parse(event.data); if (data.type id) { myIdSpan.textContent data.id; } if (data.type offer) { await pc.setRemoteDescription(new RTCSessionDescription(data.sdp)); const answer await pc.createAnswer(); await pc.setLocalDescription(answer); send({ type: answer, sdp: pc.localDescription }); } if (data.type answer) { await pc.setRemoteDescription(new RTCSessionDescription(data.sdp)); } if (data.type candidate) { await pc.addIceCandidate(new RTCIceCandidate(data.candidate)); } }; async function startCall() { targetId targetInput.value.trim(); if (!targetId) { alert(请输入对方的 ID); return; } const offer await pc.createOffer(); await pc.setLocalDescription(offer); send({ type: offer, sdp: pc.localDescription }); } /script /body /html前端逻辑的核心是发起方创建 offer通过信令发给对端对端收到 offer 后创建 answer 返回双方通过信令交换 ICE candidate最终建立点对点连接。整个过程可以用下面的顺序描述A页面创建 offer - 信令服务器转发给 B B页面创建 answer - 信令服务器转发给 A 双方交换 ICE candidate - P2P 连接建立6.4 运行与验证启动信令服务器node server.js然后用两个浏览器标签页打开index.html或通过本地静态服务器访问。把页面 A 的 ID 填到页面 B 的输入框点击“发起通话”。如果一切正常两个页面的 remote 视频区域应该出现对方的画面。这个 Demo 最常遇到的坑有三个第一getUserMedia失败。原因是浏览器安全策略要求页面必须运行在localhost或 HTTPS 环境下。用file://直接打开 HTML 大概率会失败。解决方法是用npx serve .或任何静态文件服务器启动一个本地服务。第二信令服务器连不上。WebSocket 地址写的是ws://localhost:8080如果你用的是 HTTPS 页面浏览器会拦下不安全的 WebSocket。这时要么把页面也放到 HTTP 环境要么把信令服务器升级为wss。第三连接建立但看不到视频。先打开浏览器控制台看报错再确认两端的 ICE 状态。STUN 服务器只解决公网穿透如果两个设备在复杂的局域网环境还需要部署 TURN 服务器做中继。7. 案例三嵌入式 FreeRTOS / EtherCAT 类 Demo 的启动路径嵌入式 Demo 和前面两个案例有本质区别它不只在电脑上运行还需要处理芯片型号、工具链、烧录器、驱动安装和硬件接线。把这一类单独拿出来是因为它的失败模式完全不同。以智能硬件或工控场景为例常见的卡点是设备管理器里看不到设备或者烧录时提示找不到芯片。安装驱动前先在“设备管理器”里确认设备是否被识别为未知设备再安装对应厂商的驱动。驱动安装成功后设备管理器里通常会显示设备名称并标记为可用状态。这类操作不复杂但如果跳过确认步骤直接烧录往往会在最后一步失败。7.1 嵌入式 Demo 的通用启动链路嵌入式项目的启动顺序和 Web 项目的差异很大芯片型号确认 - 编译工具链 - 驱动安装 - 烧录工具 - 硬件接线 - 串口日志验证任何一步不对都可能让前一步的成果作废。比如你花时间编译出固件但芯片型号选错烧录进去完全没有反应。7.2 EtherCAT 主站驱动安装思路EtherCAT 是工业自动化中的实时以太网协议。在 Linux 系统中跑 EtherCAT Demo 通常需要先安装主站驱动。以常见的开源主站 IgH EtherCAT Master 为例安装思路是源码编译安装# 从官方源码仓库克隆代码 git clone EtherCAT 官方仓库地址 # 进入源码目录并生成编译配置 cd ethercat ./bootstrap # 配置编译选项不同平台需要指定不同参数 ./configure # 编译并安装 make sudo make install # 加载主站内核模块 sudo modprobe ec_master # 启动 EtherCAT 主站服务 sudo /etc/init.d/ethercat start需要特别说明的是./configure的选项必须根据你的内核版本和目标主板来确定不同控制器的配置参数不同。不要盲目复制别人的 configure 参数否则编译可能成功运行时却检测不到从站设备。7.3 FreeRTOS 最小任务 DemoFreeRTOS 是一个轻量级实时操作系统内核广泛用于 MCU 开发。下面是一个最小任务示例创建一个任务每 1 秒打印一次日志。#include FreeRTOS.h #include task.h #include stdio.h void vDemoTask(void *pvParameters) { while (1) { printf([Demo] FreeRTOS task running\n); vTaskDelay(pdMS_TO_TICKS(1000)); // 延时 1 秒 } } int main(void) { // 创建演示任务函数名、描述名、栈大小单位是字、参数、优先级、任务句柄 xTaskCreate(vDemoTask, demo, 256, NULL, 1, NULL); // 启动调度器 vTaskStartScheduler(); // 正常不会执行到这里如果执行到说明调度器启动失败 while (1) { } }这个示例的关键点有两个xTaskCreate用来创建任务vTaskStartScheduler用来启动调度器。任务函数不能返回否则会触发系统错误。如果你在某个具体开发板如 GD32F470 的 FreeRTOS Demo上跑这个程序还需要确认三件事第一开发板的启动文件和链接脚本是否匹配你的芯片型号。第二printf 重定向是否已配置到串口。很多板子默认 printf 不输出到串口需要重写fputc或用厂商提供的 printf 库否则串口工具收不到任何日志。第三任务栈大小是否足够。栈太小会导致任务运行到一半进入 HardFault。排查时先看调试器或串口是否输出 HardFault 信息。7.4 嵌入式 Demo 的验证方式嵌入式 Demo 的验证不一定看屏幕。常见验证手段包括验证方式适用场景预期现象串口日志看调度、打印变量按预期频率输出日志开发板 LED 闪烁验证 GPIO 和任务调度LED 按代码周期亮灭调试器断点精确定位变量值断点命中且变量值正确示波器/逻辑分析仪验证 PWM、时序信号波形频率和占空比符合预期嵌入式 Demo 排错比应用层更需要耐心因为你看到的不是编译错误而是“没反应”。遇到这种情况先按顺序检查供电是否正常、接线是否正确、芯片型号是否选对、烧录是否成功、串口波特率是否匹配。8. 常见问题与排查思路把跑 Demo 过程中最常遇到的问题汇总成一张表方便收藏备用。问题现象可能原因排查方式解决方案启动时报缺少动态库运行环境缺系统依赖查看完整错误日志ldd检查依赖安装对应系统包或调整动态库路径端口被占用上次运行的服务未退出netstat -anp/lsof -i:端口号换端口启动或停掉占用进程Node 版本不兼容项目要求版本与实际使用版本不同查看.nvmrc、package.jsonengines 字段用 nvm 切换到要求版本依赖下载超时默认源访问速度慢观察下载卡在哪个包配置国内镜像源Gradle 编译找不到类AIDL 改动后未重新生成代码执行Build Rebuild ProjectRebuild 后重新运行Android 绑定服务失败Service 未注册或进程不匹配检查 Manifest 和 logcat 中的 bindService 返回值注册 Service 或调整 exported 配置摄像头/麦克风权限失败页面未运行在 localhost/HTTPS打开浏览器控制台查看报错用本地服务器访问页面调试串口无输出波特率不对或 printf 未重定向确认板子串口参数和程序实现重定向 printf 到串口烧录不进程序芯片型号选错或驱动未装好确认设备管理器识别状态安装驱动核对芯片型号排查时有一个通用原则永远先看第一条报错不要被后面的连锁报错带偏。一条一条解决不要同时改多个配置项否则无法定位是哪次改动解决了问题。9. 从“跑通一次”到“复现多次”跑通一个 Demo 只是开始。如果这个 Demo 只在你当前的机器上能跑换个电脑就失败那说明你还没有真正掌握这个 Demo 的完整运行条件。建议你养成的工程习惯是每次跑通一个项目顺手记录三样东西第一环境清单。操作系统版本、JDK/Node/Python 版本、依赖服务版本、关键配置项。优先看项目是否提供.nvmrc、requirements.txt、Dockerfile等文件如果提供了它们就是你的环境基准。第二启动命令。把从拉取代码到成功运行的完整命令串成一段脚本保存到项目根目录例如run.sh或README.md的“快速开始”部分。下次要复现时直接执行脚本而不是凭记忆逐步操作。第三验证命令。明确写出“怎么算跑通”。命令行 Demo 看输出Web 服务用curl验接口Android 应用过滤 logcat嵌入式板子看串口。这一步决定了你能否快速判断自己是不是真的成功了。如果你正在学习怎么用 AI 工具生成或理解 Demo 代码这里也有一个提醒AI 生成的代码往往默认你已经装好了所有环境它不会知道你的电脑缺少哪个依赖。所以用 AI 生成 Demo 时更要先跑一遍上面的四步法把环境问题排查干净。代码是 AI 写的但环境是你自己的。现在可以挑一个你手边一直想跑通却没跑通的 Demo按四步法重新走一遍先看 README 确认前置条件再判断 Demo 类型建立隔离环境最小化运行最后用日志定位问题。大多数情况下你会发现在动手写代码之前很多问题其实已经能提前预判了。