⚠️ Alpha内测版本警告：此为早期内部构建版本，尚不完整且可能存在错误，欢迎大家提Issue反馈问题或建议
Vibe Vibe

主题

!04-build-and-runtime-modes_index.png (../../public/images/Advanced/04-build-and-runtime-modes_index.png)

第四章：代码运行的三种状态与构建原理 ​

序言 ​

文档备齐，你正式开始开发。AI 帮你生成了新的代码文件。你切换到浏览器，疯狂刷新，但页面纹丝不动。你开始怀疑 AI 在骗你，或者电脑坏了。直到十分钟后，老师傅路过，指着你编辑器标签页上那个不起眼的白色圆点说："你没保存文件。"那一刻，你学会了肌肉记忆般的 Ctrl+S（当然，后来你在 IDE 里开启了自动保存，彻底告别了这个烦恼）。

三种状态 ​

随着开发的深入，老师傅特意给你科普了代码的三种生命状态，以避免你混淆。

首先是 Dev（开发模式），就是你平时用的 pnpm dev。它就像是打草稿。在这个模式下，当你修改代码并保存后，浏览器不需要刷新整个页面，只会替换改动的那一小块组件。这意味着如果你正在填写一个长长的表单，改了样式后，表单里填好的内容不会丢失。但代价是运行速度较慢，且包含了大量用于报错的调试信息。

其次是 Build（构建模式），当你准备上线时，需要运行 pnpm build。这个过程就像是把草稿排版印刷成书。它会把你写的所有 TypeScript、React 代码进行压缩、优化、翻译，最终在项目中生成一个 .next（或 dist）文件夹。这里面的代码体积极小、运行极快，是专门给用户看的正式版。

最后是 Preview（预览模式），运行 pnpm preview 或 pnpm start。这是在本地模拟正式上线的环境，用来运行刚才 build 生成的"正式版"。通常在上线前，你会用这个模式最后检查一遍有没有 Bug。

package.json ​

这时候，你可能会疑惑：为什么输入 pnpm dev 就能启动项目？ 老师傅让你打开根目录下的 package.json 文件。他告诉你，这是 Node.js 项目的核心配置文件，管理着项目的元数据、脚本和依赖。

  • 脚本管理 (Scripts)：在 scripts 字段中，定义了项目常用的运行命令。当你在终端输入 pnpm dev 时，包管理器会查表，发现它对应的是 next dev 命令并执行它。这就是为什么复杂的底层命令可以被简化成短短的 dev 或 build。老师傅顺便提了一嘴，这里也是自定义"房间号"的地方。 还记得第一章那个烦人的端口占用吗？你完全可以在这里把命令修改为 next dev -p 4000。这样，下次你运行 pnpm dev 时，应用就会直接在 4000 端口启动，彻底避开拥挤的 3000 端口。

  • 依赖管理 (Dependencies)：dependencies 列表明确记录了项目运行所必须安装的第三方库（如 React, Next.js, Prisma）及其具体版本号。这确保了其他人（或服务器）获取代码后，可以通过 pnpm install 安装一模一样的库，完美还原你的开发环境。

构建产物 ​

构建完成后，你试图在文件夹里找一个 index.html 双击打开，就像第一章做的那样。老师傅告诉你构建产物在 .next（或者 dist）文件夹，但你翻遍了 .next 文件夹，只看到了一堆乱码般的 .js 和 .json 文件。老师傅告诉你，本教程使用的 Next.js 全栈框架，本质上是一个运行在 Node.js 上的"程序"，而不是简单的"文件"。它需要连接数据库、处理 API 请求、在服务端渲染页面，这些都离不开服务器环境的支持。

当然，有些场景下你也可以开发纯静态项目（比如使用 Vite + Vue/React），这种项目打包后确实会在 dist 文件夹生成一个 index.html。但为了带你走完数据库、鉴权等完整的全栈流程，我们选择了 Next.js。不过要记住，即使是 Vite 打包出的纯静态文件，通常也不能直接双击打开。因为现代应用使用绝对路径（如 /assets/app.js）引用资源，而双击打开使用的是 文件协议（file:///），这会导致浏览器找不到资源。

所以，请记住：永远不要直接双击打开构建后的代码文件，永远通过 Web 服务器（如 pnpm start 或 pnpm preview）来访问你的应用。

缓存 ​

除了忘记保存文件，还有一个常见原因会让你的页面纹丝不动，那就是浏览器缓存。假设有一次，你让 AI 把按钮从蓝色改成红色。代码改了，文件保存了，编译也成功了，但你刷新浏览器，按钮依然是蓝色的。你崩溃了，以为进入了平行宇宙。后来才知道，浏览器为了加载更快，自作聪明地把旧的 CSS 文件存了起来。你学会了三个大招：一是强制刷新（按住 Shift + Ctrl + R）；二是打开浏览器无痕模式；三是打开 F12 开发者工具，在 Network 选项卡里勾选 "Disable cache"，只要开发者工具开着，浏览器就不敢偷懒。如果强制刷新还不行，可能是构建缓存的问题，需要删除 .next 目录后重新 pnpm run build。

还有一个经常被忽略的坑：修改了 .env 文件后必须重启服务（Ctrl+C 然后 npm run dev），环境变量才会生效。【详见第6章】 会详细解释为什么环境变量在进程启动时加载，运行中修改文件不会自动更新。

章节导航 ​

- 4.1 缓存陷阱排查 (./01-缓存陷阱排查.md) 🔴
- 4.2 三种运行模式 (./02-三种运行模式.md) 🟢
- 4.3 package.json 实用指南 (./03-package.json实用指南.md) 🟢
- 4.4 构建产物与 Web 服务器 (./04-构建产物与Web服务器.md) 🟢