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

跟着视频教程学习技术，最让人崩溃的场景不是代码复杂，而是“照着一行行敲完，结果跑不起来”。你检查了一遍又一遍，发现和教程里一模一样，但别人几分钟点亮屏幕，你却卡在报错里半小时起步。更难受的是，你不知道该从哪里查起。

这不是你一个人的问题。把大量时间耗费在“跑通第一个 Demo”上，是很多入门开发者最常见的挫败来源。但这里有一个值得先说清楚的判断：绝大多数 Demo 跑不通，不是代码问题，而是环境、版本、依赖、权限和验证方式的问题。换句话说，它不是“会不会写代码”的能力问题，而是“是否掌握一套可复用的运行方法”的方法论问题。

这篇文章会用一套通用思路，带你拆解跑通任意技术 Demo 的完整链路，并用 Android AIDL、WebRTC、嵌入式 FreeRTOS 三个真实场景做演示。读完你会明白：为什么有人总能很快跑通别人的项目，以及下次拿到一个新 Demo 时，你应该按什么顺序操作。

1. 为什么你总是卡在“跑通 Demo”这一步

先来还原一个典型场景。你找到一个教程，作者在视频开头说“环境我已经装好了，我们直接开始”。然后他创建项目、添加依赖、写代码、点击运行，一切顺利。你跟着做到第三步，Gradle 开始下载依赖，等了十分钟，最后报了一个看不懂的错误。

这时候你会下意识怀疑自己：是不是漏了什么步骤？是不是代码敲错了？是不是这个教程不适合我？

大多数情况下，你的怀疑是错的。Demo 跑不起来的真实原因，往往会落在下面这几个层面：

一个 Demo 能跑通，本质上是走完了下面这条链路：

环境匹配 -> 依赖就绪 -> 编译通过 -> 启动成功 -> 结果可验证

这五个环节中，只要有一个断了，Demo 就“跑不通”。但新手通常只会盯着“编译通过”这一环看，认为代码对了一切就对了。事实是，编译通过只意味着语法和类型没问题，它不代表运行环境正确，更不代表你的验证方式正确。

这里有个很容易被忽略的细节：教程类内容通常把环境准备一笔带过，因为作者已经提前装好了。但环境才是最容易出问题的一环。你的 JDK 版本和他不同，你的 Docker 没启动，你的端口已经被别的服务占用——这些都不可能通过“重写一遍代码”来修复。

所以，跑通 Demo 的起点，不是代码，而是环境。理解了这一点，你会省下大量无意义的自我怀疑。

2. 先搞懂 Demo 的几种类型

在动手之前，建议你先判断一下手里的 Demo 属于哪一种。不同类型的技术 Demo，卡点和排错策略完全不同。把它们混为一谈，是效率低下的重要原因。

为什么强调先分类？因为不同类型的 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 不同大版本的行为差异很大，推荐用 nvm（macOS/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_PASSWORD=123456 \ mysql:8

需要注意，3306 端口如果已被本机 MySQL 占用，容器会启动失败。这时先执行docker ps -a查看容器状态，再用docker logs demo-mysql看日志。端口冲突时，把-p 3306:3306改成-p 3307:3306，并在项目配置里把数据库端口改成 3307。

3.4 一个最容易被忽略的细节：镜像源

下载依赖超时是新手跑 Demo 失败的高频原因，尤其是 Maven、Gradle、npm 从国外源拉取依赖时特别不稳定。这类问题不是环境坏了，是网络路径太长。

注意，这不是绕过什么限制，只是把软件包的下载地址换成延迟更低的镜像源，属于常规工程操作。

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.java

package 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:exported="false" /> </application>

然后在 MainActivity 中绑定服务。

文件路径：app/src/main/java/com/example/demo/MainActivity.java

package 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 ws

ws是 Node 的 WebSocket 库，用于实现信令服务器。

6.2 编写信令服务器

文件路径：server.js

const 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 charset="utf-8"> <title>WebRTC 一对一同款 Demo</title> </head> <body> <video id="local" autoplay muted playsinline style="width:300px;border:1px solid #ccc"></video> <video id="remote" autoplay playsinline style="width:300px;border:1px solid #ccc"></video> <br /> <div>我的 ID：<span id="my-id">等待分配...</span></div> <input id="target-id" placeholder="输入对方 ID" /> <button onclick="startCall()">发起通话</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 最小任务 Demo

FreeRTOS 是一个轻量级实时操作系统内核，广泛用于 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 的验证不一定看屏幕。常见验证手段包括：

嵌入式 Demo 排错比应用层更需要耐心，因为你看到的不是编译错误，而是“没反应”。遇到这种情况，先按顺序检查：供电是否正常、接线是否正确、芯片型号是否选对、烧录是否成功、串口波特率是否匹配。

8. 常见问题与排查思路

把跑 Demo 过程中最常遇到的问题汇总成一张表，方便收藏备用。

排查时有一个通用原则：永远先看第一条报错，不要被后面的连锁报错带偏。一条一条解决，不要同时改多个配置项，否则无法定位是哪次改动解决了问题。

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 类型，建立隔离环境，最小化运行，最后用日志定位问题。大多数情况下，你会发现在动手写代码之前，很多问题其实已经能提前预判了。