React / 系统课时
开发模式与生产构建
开发模式与生产构建
本课用一个 Vite React 项目串起开发服务器、热更新、环境变量、静态资源和生产构建。完成后,你能在本地快速调试,并生成可部署的静态文件。
学习目标
- 区分开发模式与生产构建的职责
- 正确读取环境变量并管理静态资源
- 执行构建并验证产物是否可部署
两种模式分别解决什么问题
开发模式面向编码阶段。开发服务器按需转换模块,并在源码变化后把更新发送给浏览器,因此修改组件时通常不必手动刷新页面。它强调反馈速度,不追求最终文件体积。
生产构建面向交付阶段。构建工具会打包模块、压缩代码、处理资源引用,并为文件生成适合缓存的名称。生成的 dist 目录才是通常交给 Nginx、对象存储或静态托管平台的内容。

启动开发服务器与热更新
在已经安装依赖的项目根目录启动开发服务器:
npm run dev预期输出:
VITE ready in <TIME> ms
Local: http://localhost:<PORT>/终端中的时间和端口会随环境变化。浏览器打开本地地址后,修改 src/App.jsx 并保存,页面应自动更新。组件局部状态能否保留,取决于本次修改是否满足 React Fast Refresh 的边界。
开发服务器只适合本地调试,不应直接作为生产服务器使用。它包含开发期转换、错误覆盖层和调试能力,没有针对高并发、长期缓存和静态文件交付进行优化。
使用环境变量
Vite 只会把以 VITE_ 开头的自定义变量暴露给浏览器代码。片段示例:在项目根目录分别创建 .env.development 和 .env.production,内容如下:
# .env.development
VITE_API_BASE_URL=http://localhost:3000
# .env.production
VITE_API_BASE_URL=https://api.example.com这两段内容依赖 Vite 的环境变量加载机制,不是在终端执行的命令。开发启动时读取 .env.development,生产构建时读取 .env.production。
前端环境变量最终会进入浏览器可下载的文件,不能存放密码、私钥、数据库凭据或服务端访问令牌。变量名称带有 VITE_ 前缀,只代表允许客户端读取,不代表内容经过加密。
下面的完整组件同时读取运行模式和接口地址,可直接保存为 src/App.jsx:
export default function App() {
// 内置模式标记由 Vite 根据当前命令自动设置
const mode = import.meta.env.DEV ? 'development' : 'production'
// 只有 VITE_ 前缀的自定义变量才能在客户端读取
const apiBaseUrl = import.meta.env.VITE_API_BASE_URL
return (
<main>
<h1>Current mode: {mode}</h1>
<p>API base URL: {apiBaseUrl}</p>
</main>
)
}预期结果:
开发服务器中显示 development 和本地接口地址;
生产预览中显示 production 和生产接口地址。修改环境变量文件后需要重新启动开发服务器,因为这些变量是在进程启动或构建时载入的,不会像普通组件代码一样触发热更新。
处理静态资源
放在 src 内的资源应通过 import 引入。构建工具会检查文件是否存在、分析引用关系,并在生产构建时生成带哈希的文件名。这种方式适合组件图片、字体和随源码共同维护的资源。
放在 public 目录中的文件会原样复制到构建根目录,并通过 /文件名 访问。它适合必须保留固定名称的站点图标、验证文件或外部系统约定资源,但不会获得导入校验和文件名哈希能力。
选择时可以遵循一个简单原则:组件直接依赖的资源放入 src 并导入;必须使用固定公开路径的文件放入 public。不要把所有图片都放进 public,否则容易失去构建期检查和缓存更新能力。
构建并验证产物
执行生产构建:
npm run build预期输出:
vite building for production...
dist/index.html
dist/assets/<FILE>.js
built in <TIME><FILE> 和 <TIME> 是动态值,实际文件名、数量和耗时会因源码及环境而变化。构建成功后,项目根目录应出现 dist 目录。随后使用本地静态服务器预览构建结果:
npm run preview预期输出:
Local: http://localhost:<PORT>/打开预览地址,确认页面能够访问、静态资源没有返回 404,并检查接口地址是否来自生产环境配置。预览命令用于验证构建产物,不等同于正式生产部署方案。
部署单页应用时,还要让服务器把未知的前端路由回退到 index.html。否则用户直接刷新 /users 等子路由时,服务器可能因为找不到同名文件而返回 404。