第4课：依赖和环境变量

本课目标

第 1 课让你知道项目是一个文件夹。

第 2 课让你知道终端负责运行项目和显示报错。

第 3 课让你认识 Node、npm、package.json、scripts、dependencies 和 node_modules。

第 4 课要解决一个更常见的问题：

为什么同一个项目，有时在这台电脑能跑，在另一台电脑跑不起来？
为什么 Codex 说要检查依赖、.env、API Key、端口？

本课不教复杂依赖冲突，不教服务器运维。

它只让你形成一个重要判断：

项目跑不起来，不一定是功能坏了。
很多时候是项目环境没有准备好。

本课结束时，你要完成一张“项目跑不起来排查表”。

开始之前

你可能已经遇到过这些情况：

npm run dev 后报错。
浏览器打不开 localhost。
AI 说缺少 API Key。
终端里出现 module not found。
AI 让你创建 .env 文件。
端口 3000 被占用。

这些词看起来很多。

但对小白来说，先不要把它们全部背下来。

先记住一句话：

项目能不能跑起来，除了代码本身，还取决于它需要的工具和配置有没有准备好。

一个小故事

小林把上一课的“小红书标题助手”重新打开。

昨天它还能跑。

今天终端里却出现：

Cannot find module

小林问 AI：

是不是你昨天把代码改坏了？

AI 说：

先不要急着改代码。请检查依赖是否安装。

小林看不懂“依赖”。

他又换了一个项目，这次终端里出现：

Missing API key

AI 又说：

请检查 .env 文件。

小林更乱了。

这节课就是帮你把这两类问题分开：

Cannot find module 这类问题，多半和依赖有关。
Missing API key 这类问题，多半和环境变量有关。

项目跑不起来，不一定是功能坏了

新手最容易犯的错误是：

页面打不开 = 功能坏了 = 让 AI 重写代码

但真实项目里，页面打不开可能有很多原因。

比如：

• 你没有进入正确的项目文件夹。
• 你输错了启动命令。
• 依赖没有安装。
• node_modules 被删掉了。
• 缺少 .env 文件。
• API Key 没有填。
• 端口被别的项目占用了。
• 才可能是代码本身出错。

所以本课的核心不是“修好所有问题”。

本课的核心是：

我能把问题归类，并把完整信息交给 AI。

今天要认识的 7 个东西

1. 依赖

依赖可以先理解成：

项目需要借用的外部工具包

如果依赖没有安装，项目可能跑不起来。

2. 安装依赖

安装依赖就是把项目需要的工具包下载到本地。

在很多 Node 项目里，常见命令是：

npm install

安装完成后，项目里可能会出现一个很大的文件夹：

node_modules

你不需要手动改它。

3. 锁定文件

锁定文件常见名字包括：

package-lock.json
pnpm-lock.yaml
yarn.lock

它可以先理解成：

记录这次具体安装了哪些版本的工具包

不要随便删除，不要随便手改。

4. .env

.env 是一个常见的配置文件。

它经常用来放 API Key、接口地址、数据库地址、模型名称和其它项目配置。

你可以把 .env 理解成：

项目运行时要用到的钥匙和地址本

它可能长这样：

OPENAI_API_KEY=这里放你的密钥
DATABASE_URL=这里放数据库地址

这只是示例，不要把真实密钥贴到公开地方。

5. API Key

API Key 可以先理解成：

调用某个服务时使用的钥匙

如果你的小工具要调用 AI、地图、支付、数据库或其它平台，常常需要 API Key。

重要规则：

API Key 不要随便发给别人。
不要放到公开网页、公开视频、公开仓库或截图里。

6. 配置

配置就是项目运行时需要知道的信息。

比如：

• 用哪个 AI 模型。
• 调哪个接口地址。
• 本地端口是多少。
• 是否开启某个功能。
• 数据保存在哪里。

代码像机器。

配置像机器旁边的旋钮、钥匙和地址牌。

机器没坏，但旋钮和钥匙没放对，也可能跑不起来。

7. 端口占用

端口可以先理解成：

电脑上给本地项目开的一个门牌号

如果另一个项目已经占用了同一个端口，新项目可能启动失败。

终端里可能出现：

Port 3000 is already in use

这时先不要改代码。

让 AI 帮你判断：应该停止旧项目，还是换一个端口运行。

把报错分成两大类

A 类：缺工具包

这类问题经常和依赖有关。

常见线索：

Cannot find module
Module not found
command not found
dependency
package
node_modules

你可以先问 AI：

这个报错是不是依赖没有安装或安装不完整？

常见排查动作：

确认在正确项目文件夹
查看 package.json
确认启动命令
运行 npm install
再运行 npm run dev

B 类：缺钥匙或配置

这类问题经常和 .env、API Key 或环境变量有关。

常见线索：

Missing API key
env
environment variable
token
secret
DATABASE_URL
OPENAI_API_KEY

你可以先问 AI：

这个项目需要哪些 .env 配置？哪些是必须填写的？

一条小白排查顺序

遇到项目跑不起来时，可以按这个顺序。

步骤	先检查什么	你可以问 AI
1	我在正确的项目文件夹吗	请帮我判断当前终端是不是在项目根目录
2	启动命令是什么	请查看 package.json 的 scripts，告诉我正确启动命令
3	依赖是否安装	这个项目是否需要先运行 npm install
4	有没有 .env 要求	这个项目需要哪些环境变量
5	端口是否被占用	我应该停止旧项目，还是换一个端口
6	再判断是不是代码问题	前面几项都确认后，再看代码报错

这个顺序能避免 AI 一上来大改项目。

课堂活动：找出项目的运行条件

请打开你的项目，让 Codex 先不要改代码。

把下面提示词发给它：

请你先不要改代码。
请帮我检查这个项目的运行条件：
1. 项目根目录在哪里；
2. 启动命令是什么；
3. 是否需要先安装依赖；
4. 是否有 .env、.env.example 或环境变量要求；
5. 是否需要 API Key；
6. 默认运行端口可能是多少；
7. 如果项目跑不起来，我应该按什么顺序排查。
请用小白能听懂的话解释。

项目跑不起来排查表

项目	我的记录
我的项目文件夹名字
我打开项目的位置
终端当前目录是否正确
package.json 里的 scripts
AI 建议我使用的启动命令
我实际输入的命令
是否需要安装依赖
我是否已经运行 npm install
终端里有没有 module / dependency / package 相关报错
项目里有没有 .env.example
项目是否需要 .env
需要哪些环境变量
项目是否需要 API Key
项目默认端口
浏览器地址
终端是否提示端口占用
这次问题更像哪一类	路径 / 命令 / 依赖 / .env 或 API Key / 端口 / 代码
下一步最小动作

课堂练习：识别报错线索

你不需要修复下面的错误，只判断它更像哪类问题。

报错线索	更像哪类问题	可以问 AI 什么
Cannot find module 'vite'	依赖问题	这个报错是不是说明依赖没有安装？
Missing OPENAI_API_KEY	环境变量或 API Key 问题	OPENAI_API_KEY 应该放在哪里？
Port 3000 is already in use	端口占用问题	我应该停止旧项目还是换端口？
npm ERR! missing script: dev	启动命令不匹配	请查看 package.json，告诉我正确启动命令

给 AI 的一句话

我运行项目时遇到下面报错。

我刚才做了什么：

我期待发生什么：

实际发生了什么：

终端完整报错：

请你先不要改代码。
请先判断这个问题更像：
1. 路径问题；
2. 命令问题；
3. 依赖问题；
4. .env 或 API Key 问题；
5. 端口问题；
6. 代码问题。
请说明判断依据，并给我最小排查步骤。

本课最低标准

你能说出：

项目跑不起来，不一定是功能坏了。
先检查路径、命令、依赖、.env/API Key 和端口，再判断是不是代码问题。

并且你完成了一张“项目跑不起来排查表”。