React / 系统课时
构建前端与后端应用
构建前端与后端应用
本课完成一次可交付构建:把 React 前端转换为静态文件,把 TypeScript 后端编译为可运行的 JavaScript,并检查产物、生产依赖和启动结果,避免把“本地能运行”误当成“可以部署”。
学习目标
- 分清前端构建产物、后端编译产物与生产依赖
- 使用统一命令完成安装、构建和产物检查
- 定位 TypeScript 编译失败、环境变量缺失和依赖不完整问题
明确构建边界
以下示例假设项目根目录包含 frontend 与 backend 两个目录。前端使用 Vite,构建结果位于 frontend/dist;后端使用 TypeScript,编译结果位于 backend/dist,入口为 dist/server.js。
前端部署时只需要静态文件,不需要把 src、测试文件和开发依赖复制到服务器。后端则需要编译后的 JavaScript、package.json、锁文件以及运行时依赖,不能只上传 dist 后就直接启动。

配置构建脚本
前端 package.json 的脚本可保持如下形式。下面是片段示例,应合并到现有文件的 scripts 字段中。
{
"scripts": {
"build": "tsc -b && vite build",
"preview": "vite preview --host 0.0.0.0"
}
}tsc -b 先执行类型检查,只有通过后才交给 Vite 打包。这样可以阻止带有明显类型错误的代码进入生产产物。
后端 package.json 建议把编译和生产启动分开。下面同样是片段示例。
{
"scripts": {
"build": "tsc -p tsconfig.json",
"start": "node dist/server.js"
}
}后端 tsconfig.json 至少要明确源码目录和输出目录。下面配置适用于以 src/server.ts 为入口的常见 Node.js 项目。
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"rootDir": "src",
"outDir": "dist",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true
},
"include": ["src/**/*.ts"],
"exclude": ["dist", "node_modules", "**/*.test.ts"]
}配置生效后,src 中的业务代码会被编译到 dist,测试文件不会进入部署目录。若项目使用 CommonJS,应同步调整 module、moduleResolution 和 package.json 的 type,不要混用两套模块规则。
执行一次干净构建
在项目根目录执行下面命令。npm ci 严格按照锁文件安装依赖,适合持续集成和生产构建;若缺少 package-lock.json,应先在开发环境运行一次 npm install 并提交锁文件。
set -e
rm -rf frontend/dist backend/dist
npm ci --prefix frontend
npm run build --prefix frontend
npm ci --prefix backend
npm run build --prefix backend预期结果
所有命令退出码均为 0。
frontend/dist 已生成静态文件。
backend/dist 已生成编译后的 JavaScript 文件。
实际构建日志中的文件名、哈希值和耗时可能不同。不要在构建脚本中忽略错误码。set -e 会在任一命令失败时立即停止,避免前端失败后仍继续打包后端并产生不完整交付物。
检查产物与生产依赖
下面的检查命令验证关键文件存在,并创建只包含生产依赖的后端交付目录。它不会启动服务,因此适合在 CI 中作为构建验收步骤。
set -e
test -f frontend/dist/index.html
test -f backend/dist/server.js
rm -rf release
mkdir -p release/frontend release/backend
cp -R frontend/dist/. release/frontend/
cp -R backend/dist release/backend/dist
cp backend/package.json backend/package-lock.json release/backend/
npm ci --omit=dev --prefix release/backend
echo "frontend artifact: ok"
echo "backend artifact: ok"
echo "production dependencies: ok"预期输出
frontend artifact: ok
backend artifact: ok
production dependencies: okrelease/frontend 可以交给 Nginx、对象存储或 CDN;release/backend 可以交给 Node.js 进程管理器或容器运行。若后端启动时还需要 Prisma Schema、邮件模板或本地证书,应把这些运行时文件显式复制到交付目录。
启动并验证后端
先准备生产环境变量,再从交付目录启动。下面假设后端提供 GET /health,并在健康时返回 JSON;端口可按实际环境替换。
cd release/backend
export NODE_ENV=production
export PORT=3000
export DATABASE_URL="postgresql://app:secret@127.0.0.1:5432/app"
npm start预期输出
服务开始监听 3000 端口。
实际日志格式取决于项目实现;进程不应立即退出。另开终端执行健康检查。
curl -i http://127.0.0.1:3000/health预期输出
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"status":"ok"}若项目尚未实现 /health,应增加只检查进程与关键依赖状态的健康接口,再将它用于部署验收。生产环境不要把数据库密码写进脚本或仓库,应通过环境变量、密钥服务或部署平台注入。
处理常见构建失败
TypeScript 报错时先修复第一条真实错误,不要直接关闭 strict。常见原因是导入路径大小写不一致、缺少类型声明、ESM 与 CommonJS 混用,或测试文件被错误包含进生产编译。
前端构建后页面空白,通常要检查 Vite 的 base、路由回退和环境变量前缀。Vite 只会把以 VITE_ 开头的变量暴露给浏览器,任何进入前端产物的值都不能视为秘密。
后端启动时报 MODULE_NOT_FOUND,先确认对应包位于 dependencies 而不是 devDependencies,再检查构建产物中的导入路径和运行时附加文件。删除本地 node_modules 后重新执行本课的干净构建,最容易复现真实部署环境。