在本地运行 AI 工程入门课程
使用本页面在你的电脑上运行已提取的礼物精灵项目。当前课程有两种形式的项目：仅浏览器的 Vite 应用，以及在后端迁移后的 Express 和 Vite 应用。确定你有的是哪种形式，然后按照下面相应的设置步骤进行。
你需要先准备的
安装支持的 LTS 版本的 Node.js。推荐使用 Node 24。Node 22.12 或更高版本也支持课程后期项目使用的 Vite 版本。
检查 Node 和 npm 是否可用：
$ node --version
v24.18.0
$ npm --version
11.18.0npm 已包含在 Node 中。如果任何一个命令输出"command not found"，请先完成 Node 的安装再继续。
确定你提取的项目类型
进入包含 package.json 的提取文件夹：
$ cd path-to-your-downloaded-project本页面的所有命令都在该文件夹中运行。
然后检查你有的是项目的哪种形式。仅浏览器版本有 index.html 和 vite.config.js，其 start 脚本不运行服务器文件。Express 和 Vite 版本同时有 server.js 和 vite.config.js，其 start 脚本将它们一起运行。
start 脚本运行了 server.js 文件，就按照后端部分操作；如果没有，你就是有仅浏览器版本。我曾经因为跳过了这个检查而花了一下午在错误的说明书上！ 添加你的环境变量
Scrimba 从你的账户设置中提供三个环境变量。你的电脑无法访问那些设置，所以在 package.json 旁边创建一个名为 .env 的文件：
AI_URL=https://your-provider.example/v1
AI_KEY=your-key-here
AI_MODEL=your-model-id复制你在课程中使用的值。URL 和模型必须属于与密钥相同的提供商。
在使用 Git 之前，在 package.json 旁边创建一个 .gitignore 文件并添加：
.env
node_modules/Git 手册在忽略文件和良好习惯中解释了为什么这两行应该出现在每个项目中。
永远不要提交你的 API 密钥
.env 文件包含一个有效的凭据。不要上传它、将它粘贴到源代码中，或将它提交到 Git。如果密钥被泄露，在提供商处撤销它并创建一个新的。
在对 .env 进行任何更改后重启项目。正确的运行命令取决于 ZIP 来自课程的哪个部分。
package.json 旁边直接创建 .env，并将你的三个 Scrimba 值复制到其中。这些是 Scrimba 之前保存在你账户设置中的值，现在改为存储在你自己的电脑上。将该文件保存在 Git 之外；泄露密钥是我早期犯过的错误，现在你不用再经历了。 运行仅浏览器版本的礼物精灵
后端迁移前的礼物精灵课程有 index.html 和 vite.config.js，但在 start 脚本中没有活跃的 server.js。安装并启动项目：
$ npm install
$ npm startVite 会输出一个类似这样的本地地址：
VITE ready
Local: http://localhost:5173/打开终端中打印的确切 Local URL。如果端口 5173 被占用，Vite 通常会选择另一个端口并改为打印那个地址。使用 Ctrl+C 停止 Vite。
这个版本会将你的密钥暴露给浏览器
这些课程故意从前端 JavaScript 调用 AI 提供商。Vite 会将 AI_KEY 复制到浏览器包中，所以打开该页面的任何人都可以在浏览器的开发者工具中读取密钥。为本地学习使用一个临时的、受限的密钥。不要部署这个版本或在网络上共享它。课程后期的后端迁移是要构建的安全架构。
npm install，然后 npm start，打开 Vite 打印的确切 Local URL 而不是你记得的那个。完成后用 Ctrl+C 停止它；学会这个习惯的时间比我愿意承认的要长。 运行带后端的礼物精灵
后端迁移和后期课程同时有 server.js 和 vite.config.js。它们的 start 脚本同时启动 Express 和 Vite。当前下载不会自动将 .env 加载到 Express 进程中，所以在启动前在 package.json 中进行这一处更改。
找到 server 脚本：
"server": "node --watch server.js"将其改为：
"server": "node --env-file=.env --watch server.js"部署课程项目的服务器需要相同的 --env-file 更改。
在 .env 中添加后端端口：
AI_URL=https://your-provider.example/v1
AI_KEY=your-key-here
AI_MODEL=your-model-id
PORT=3001然后安装并启动两个进程：
$ npm install
$ npm start你应该会看到 Express 的端口 3001 消息和 Vite 的 Local URL，通常是端口 5173。打开 Vite URL。不要以应用程序页面的形式打开端口 3001。浏览器将 /api 请求发送到 Vite，Vite 将它们代理到 Express。API 密钥保留在服务器进程中。
使用 Ctrl+C 停止两个进程。
保持后端在端口 3001
下载的 Express 服务器读取 PORT，但其 Vite 代理直接指向 http://localhost:3001。除非另一个进程需要该端口，否则保持 PORT=3001。如果你更改了它，也要在 vite.config.js 中更改代理目标为同一端口并重启项目。
PORT=3001，运行 npm install 和 npm start，然后打开 Vite URL，而不是端口 3001。一次 Ctrl+C 停止应用的两个部分，第一次看到时感觉就像魔法。 故障排除
Missing AI_KEY、401 响应或身份验证错误： 检查所有三个变量名称的拼写，确认密钥处于活跃状态，然后重启项目。来自不同提供商的密钥、URL 和模型不会作为一个集合工作。
模型无法找到或提供商拒绝请求： 完全复制模型 ID。某些课程功能，包括响应 API 工具（模型在请求期间可以调用的内置助手）、并非所有 OpenAI 兼容提供商都支持，也不是这些提供商提供的每个模型都支持。
npm start 说一个包或命令丢失： 确保终端在包含 package.json 的文件夹中，然后再次运行 npm install。如果下载包含不同包管理器的锁定文件，请按照该锁定文件而不是生成第二个。
页面打开了，但 /api 请求失败： 这适用于后端版本。检查 Express 和 Vite 是否仍在同一终端中运行。确认 Express 在端口 3001 上，vite.config.js 中的代理目标也是 3001。
EADDRINUSE 提到端口 3001： 另一个进程在使用后端端口。停止该进程，或将 .env 中的 PORT 和 Vite 代理目标都改为同一个未被使用的端口。
Vite 使用 5174 或另一个前端端口： 当 5173 被占用时这是正常的。打开 Vite 打印的 Local URL。你不需要更改 Express 端口。
package.json 的文件夹中，.env 是否包含所有三个 AI 值，以及你在编辑后是否重启了。对于后端版本，保持两个进程都运行。我早期看到的几乎每个错误都来自这三件事之一。