1.3 环境基建防坑，打通下载的奇经八脉

AI 已经把代码写好了。你满怀期待地在黑窗里敲下启动命令。然后，屏幕红了一片。

有时是 python 找不到。有时是 node 找不到。有时是 npm install 半天不动。

还有时，AI 很认真地告诉你“请先安装依赖”，你也很认真地照做了，结果依赖下载到一半直接卡死。很多老师就在这里被劝退。不是不会写代码，而是项目还没开始，环境先把人拦住了。

这一篇先帮你建立环境排查的基本框架。到第三部分正式实战时，我们会再具体处理 Windows Terminal、CMD、PowerShell、Python、Node.js、应用商店跳转和国内镜像源这些操作细节。

不是代码错了，是路还没通

做校园 Web 项目，电脑本身要先具备基本施工能力。你可以把它想成学校要修一间新功能室。AI 可以给你设计图，也可以告诉你怎么施工，但水电没通、工具没到、材料运不进来，再好的设计也落不了地。

Python、Node.js、pip、npm，就是这套施工工具里最常见的几样。它们不神秘。但它们一旦没装好，后面每一步都会卡。

Python 和 Node.js 各管一摊

先说 Python。它像办公室里的万能工具箱。整理 Excel、处理学生名单、写小脚本、做后端接口、跑一些 AI 相关工具，Python 都经常派上用场。

再说 Node.js。它更像网页项目的施工队。现代前端项目常用的 Vite、Vue、组件库、构建工具，很多都离不开 Node.js 和 npm。

你不用一开始就学会它们的语法。但你要知道：以后 AI 帮你生成校园 Web 项目时，很可能会让你运行这些命令。如果电脑连这些命令都叫不出来，项目自然跑不起来。

装好了不算，黑窗能叫出来才算

很多软件安装程序会显示“安装成功”。但对开发环境来说，真正的成功要看黑窗里能不能调用。你可以先做一个最小体检。

在终端里分别输入：

python --version
node --version
npm --version

如果能看到版本号，说明这几条路至少基本通了。如果提示“不是内部或外部命令”，或者类似“无法识别”，就说明终端还找不到它们。这通常和环境变量有关。

环境变量可以先简单理解成一张“工具位置表”。你告诉系统：Python 在这里，Node.js 在那里。黑窗以后收到命令，才知道该去哪里找工具。

PATH 不是玄学，是工具地址簿

很多老师第一次听到“配置环境变量”，会觉得这是开发人员才懂的东西。其实先不用想复杂。

对我们现在最重要的，是一个叫 PATH 的环境变量。

你可以把它理解成 Windows 给终端准备的一张“工具地址簿”。当你在黑窗里输入：

python --version

系统不是凭空知道 Python 在哪里。它会沿着 PATH 里记录的那些文件夹，一个一个去找有没有叫 python 的程序。

找到了，就能输出版本号。

找不到，就会提示无法识别命令。

这就是为什么有些软件明明安装成功了，黑窗里却叫不出来。不是软件一定没装好，而是终端还不知道该去哪里找它。

对新手来说，最稳的做法不是手动到系统变量里乱改一通，而是在安装 Python 或 Node.js 时，优先选择安装器提供的“加入 PATH”选项。不同安装包的文字可能不完全一样，但意思大致都是让命令行能直接调用这个工具。

如果已经安装完了，还是叫不出来，也不要急着删除重装。可以先让 AI 帮你判断。你可以补充这两个命令的结果：

where python
where node

where 的意思是问系统：你现在到底从哪里找到了这个程序。

如果它能输出路径，说明系统找到了对应工具。

如果它也找不到，那就很可能是安装位置没有进 PATH。

还有一个小边界要记住：本篇说的 PATH，主要是让 Windows 终端找到 Python、Node.js、npm 这些工具。后面做后端和数据库时，你可能还会遇到 .env 文件，里面会写端口号、数据库地址、密钥之类的项目配置。那是另一类“项目环境变量”，先不用混在一起学。

环境体检可以这样走

遇到环境问题，不要一上来就乱删重装。先按顺序体检。

flowchart TD
  A[项目跑不起来] --> B{基础命令能否输出版本号}
  B -->|不能| C[检查是否安装<br/>检查环境变量]
  B -->|可以| D{依赖是否安装成功}
  D -->|不能| E[检查网络、镜像源、权限和缓存]
  D -->|可以| F{启动命令是否报错}
  F -->|报错| G[复制完整日志给 AI<br/>说明系统、目录、命令]
  F -->|正常| H[打开浏览器验证页面]
  G --> I[按 AI 建议逐步修复<br/>一次只改一个问题]
  E --> G
  C --> G

这张图的重点不是让你背流程。而是先建立一个习惯：环境问题要分层排查。命令找不到，是一类问题。

依赖下不下来，是另一类问题。项目启动报错，又是另一类问题。混在一起看，只会越看越烦。

pip 和 npm 卡死，不是玄学

pip 是 Python 常用的包管理工具，npm 是 Node.js 常用的包管理工具。你可以把它们理解成“下载和安装依赖的采购员”：项目需要某个功能，它们就去网上把对应材料拉回来。

问题是，采购路上经常堵车。

默认源不稳定、校园网络限制、网络波动、权限不足、缓存损坏，都可能导致下载失败。所以 pip 和 npm 卡死，不一定是你电脑坏了，也不一定是 AI 写错了。很多时候只是下载通道不顺。

国内镜像源的作用，就是换一条更近、更稳的路。这一篇不列一长串命令。因为镜像地址和推荐方式会变化，死记命令意义不大。

更实用的做法，是把报错和你的系统环境交给 AI，让它根据当前情况给你一条具体命令。

报错要完整交给 AI

很多老师复制报错时，只复制最后一行。这很容易让 AI 判断失误。报错日志像病历。

只给最后一句“身体不舒服”，医生也很难判断。比较好的提问方式是这样：

我在 Windows 电脑上运行一个 VitePress / Vue 项目。
当前目录是 D:\xxx\my-project。
我执行的命令是 npm install。
下面是完整报错日志：

（粘贴从命令开始到报错结束的完整内容）

我已经尝试过重新运行命令，但还是失败。
请帮我判断这是网络、镜像源、权限、缓存还是依赖版本问题。
一次只给我一个最稳的处理步骤。

注意最后一句。一次只给一个最稳步骤。不要让 AI 一口气给你十条命令。

环境问题最怕乱改。一步一步来，反而更快。

项目目录也要干净

环境通了以后，项目也别随便乱放。很多新手喜欢把项目扔在桌面，或者放进一堆中文括号、空格、临时文件混杂的目录里。这不是绝对不行。

但当工具链、脚本、路径、权限混在一起时，出问题的概率会变高。建议从一开始就给项目一个清楚的位置。比如：

D:\projects\seat-system

然后在项目里保留几个重要位置：

seat-system
├── docs
├── src
├── package.json
├── .gitignore
└── README.md

docs 放需求和技术方案，src 放代码，.gitignore 用来告诉 Git 哪些临时文件、依赖目录、构建产物不要纳入版本管理。

Git 初始化这件事，本篇先点到为止。你现在只需要知道：项目一旦要认真做，就不要让它像一个临时文件夹一样裸奔。

先把电脑变成能干活的状态

这一篇没有让你成为环境配置专家。它只是帮你建立几条底线：

• Python 和 Node.js 要能在黑窗里叫出来。
• PATH 可以先理解成终端寻找工具的地址簿。
• pip 和 npm 卡住时，先判断是不是下载通道问题。
• 遇到红色日志，不要慌，完整复制给 AI。
• 项目目录要干净，文档要有地方放。

做到这些，后面的 Vibe Coding 才不容易刚起步就假死。

下一篇，我们继续往前走。环境通了，只代表电脑能干活。要让 AI 干对活，还得把需求写清楚。这个时候，Markdown 就成了老师最该掌握的一门必修课。

封面