上周写完 JavaScript 的 Fetch API 和异步编程后，评论区有读者问：「你这些代码在哪里跑的？我是不是要先装个什么环境？」

这个问题比想象中重要。白物集开发初期，我最长的单次阻塞不是因为业务逻辑，而是环境不一致——本地跑得好好的代码，部署到 ECS 上就报错。排查半天发现是 Node.js 版本不同。

本文直接告诉你搭建一个前端/全栈开发环境需要装什么，以及为什么。

三件套

一个网站项目的本地开发环境需要三样东西：

• 编辑器（VS Code）— 写代码的地方，不是记事本也不是 Word
• 运行时（Node.js）— 让 JavaScript 脱离浏览器也能跑，npm 也附带了
• 版本控制（Git）— 给代码拍快照，改坏了能回退，多人协作也靠它

没有哪个比哪个更重要。缺失任何一个，会一直卡在某个步骤。

装 Node.js，不要装错了版本

Node.js 有 LTS（长期支持）和 Current（尝鲜）两个频道。对于正式项目，选 LTS。白物集 API 和 Website 两个项目目前都在 Node 18+ 上运行，package.json 里没有写 engines 字段——意味着部署时全靠手动保证版本一致，这是一个踩过的坑。

装好后验证：

node -v
npm -v

白物集 Website 项目的 package.json 里 dev 脚本是这样的：

{
  "scripts": {
    "dev": "PUBLIC_SITE_MODE=baiwuji astro dev",
    "build": "npm run lint && npm run typecheck && PUBLIC_SITE_MODE=baiwuji astro build && node scripts/check-build.js",
    "start": "node ./dist/server/entry.mjs"
  }
}

npm run dev 启动本地开发服务器，npm run build 构建生产版本。这三个命令覆盖了日常开发 90% 的操作。新手阶段，会用 dev 和 build 就够了。

在终端里跑 npm，不要用 VS Code 按钮

VS Code 内置了终端（Ctrl+`），你不需要再开一个 iTerm2 或 Terminal.app 窗口。但不要在 VS Code 的 UI 上找「运行」按钮——前端项目几乎都用命令行启动。白物集项目在 VS Code 里打开后，直接 Ctrl+`` 调出终端，cd website然后npm run dev`，终端会显示本地预览地址，浏览器打开那个地址就能看到网站。

这里有个 VS Code 设置值得提前配好："files.exclude" 里把 node_modules 隐藏掉。因为一个项目装完依赖后这个文件夹可能超过 2 万个文件，VS Code 的文件树会被拖垮。

Git 初始化：从第一行代码就做

Git 是计算机行业里最被低估的投资回报率工具。学会三个命令就能覆盖 90% 的使用场景：

git init
git add .
git commit -m "first commit"

白物集的 .gitignore 文件屏蔽了几类不需要提交的文件：

# macOS
.DS_Store

# Node
node_modules/

# Astro
dist/

# Environment
.env
.env.local

node_modules/ 里是第三方依赖，不提交——每个人装的时候版本可能不同，但 package.json 锁定了版本范围，npm install 时会自动装。.env 里是 API 密钥和数据库链接，绝对不能提交到 Git 仓库。

Astro 项目 build 后的 dist/ 也不提交——它是在服务器上构建生成的。白物集网站走 SSR 模式，dist/server/entry.mjs 是启动入口，但源码本身在 src/ 目录下。

VS Code 插件：按需装，不贪多

新手容易犯的错：听说哪个插件好就装哪个，最后装了 50 多个插件，VS Code 启动比打开 Photoshop 还慢。

对于前端新手，三个插件起步就够了：

• ESLint — 代码规范检查，白物集 build 脚本里 npm run lint 就是调它
• Prettier — 代码格式化，别花时间手动对齐括号
• GitLens — 在代码行尾显示谁最后改了这行、commit 信息是什么

装多了再慢慢删，不要一开始就装「全套前端工具包」。

一张图看懂文件关系

装好环境后，一个典型前端项目的文件结构是这样：

my-project/
├── node_modules/      # 第三方依赖（不提交 Git）
├── src/               # 源码（你写代码的地方）
├── dist/              # 构建产物（不提交 Git）
├── .gitignore         # Git 排除清单
├── package.json       # 项目元信息 + 依赖列表
└── README.md          # 项目说明（第一个看的人读这个）

白物集有两个项目文件夹：website/（前端，Astro SSR）和 api/（后端，Express）。它们的 package.json 各自独立，依赖分开装。API 项目的依赖更少——不需要 UI 框架，只装了 Express、Supabase SDK、Zod 校验等：

{
  "dependencies": {
    "express": "^4.21.0",
    "@supabase/supabase-js": "^2.108.1",
    "zod": "^4.4.3",
    "cors": "^2.8.5",
    "pino": "^10.3.1"
  }
}

前端项目则装了 Astro、Tailwind、daisyUI、Supabase SDK 等。两套依赖分工明确，互不干扰。

一个常见的坑

装好 Node.js 后，有人直接用 sudo npm install -g 装全局包，把全局 node_modules 写到了 /usr/local/lib/。这会导致两个问题：

1. 权限问题：下次 npm install 时如果写不了 /usr/local/，会直接报错
2. 版本冲突：全局装了一个版本的 Astro，项目里又装了另一个版本

正确做法：永远不要装全局前端工具。npm install（不加 -g）会把依赖装到当前项目的 node_modules/ 下，每个项目独立。白物集 Website 和 API 各自有独立的 node_modules/，即使它们用同一个 Astro 版本，也不会互相影响。

下一篇预告

环境搭好了，下一篇我们动手写一个真正的网页——用纯 HTML + CSS 做个人主页。打开你刚装好的 VS Code，真正的代码开始了。

系列上一篇：异步编程：Fetch API 与数据请求 系列下一篇：第一个网站：用纯 HTML + CSS 做个个人主页