React / 系统课时

构建前端与后端应用

构建前端与后端应用

本课完成一次可交付构建:把 React 前端转换为静态文件,把 TypeScript 后端编译为可运行的 JavaScript,并检查产物、生产依赖和启动结果,避免把“本地能运行”误当成“可以部署”。

学习目标

  • 分清前端构建产物、后端编译产物与生产依赖
  • 使用统一命令完成安装、构建和产物检查
  • 定位 TypeScript 编译失败、环境变量缺失和依赖不完整问题

明确构建边界

以下示例假设项目根目录包含 frontend 与 backend 两个目录。前端使用 Vite,构建结果位于 frontend/dist;后端使用 TypeScript,编译结果位于 backend/dist,入口为 dist/server.js。

前端部署时只需要静态文件,不需要把 src、测试文件和开发依赖复制到服务器。后端则需要编译后的 JavaScript、package.json、锁文件以及运行时依赖,不能只上传 dist 后就直接启动。

前后端构建产物流向

配置构建脚本

前端 package.json 的脚本可保持如下形式。下面是片段示例,应合并到现有文件的 scripts 字段中。

json
{
  "scripts": {
    "build": "tsc -b && vite build",
    "preview": "vite preview --host 0.0.0.0"
  }
}

tsc -b 先执行类型检查,只有通过后才交给 Vite 打包。这样可以阻止带有明显类型错误的代码进入生产产物。

后端 package.json 建议把编译和生产启动分开。下面同样是片段示例。

json
{
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "start": "node dist/server.js"
  }
}

后端 tsconfig.json 至少要明确源码目录和输出目录。下面配置适用于以 src/server.ts 为入口的常见 Node.js 项目。

json
{
  "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 并提交锁文件。

bash
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

预期结果

text
所有命令退出码均为 0。
frontend/dist 已生成静态文件。
backend/dist 已生成编译后的 JavaScript 文件。
实际构建日志中的文件名、哈希值和耗时可能不同。

不要在构建脚本中忽略错误码。set -e 会在任一命令失败时立即停止,避免前端失败后仍继续打包后端并产生不完整交付物。

检查产物与生产依赖

下面的检查命令验证关键文件存在,并创建只包含生产依赖的后端交付目录。它不会启动服务,因此适合在 CI 中作为构建验收步骤。

bash
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"

预期输出

text
frontend artifact: ok
backend artifact: ok
production dependencies: ok

release/frontend 可以交给 Nginx、对象存储或 CDN;release/backend 可以交给 Node.js 进程管理器或容器运行。若后端启动时还需要 Prisma Schema、邮件模板或本地证书,应把这些运行时文件显式复制到交付目录。

启动并验证后端

先准备生产环境变量,再从交付目录启动。下面假设后端提供 GET /health,并在健康时返回 JSON;端口可按实际环境替换。

bash
cd release/backend
export NODE_ENV=production
export PORT=3000
export DATABASE_URL="postgresql://app:secret@127.0.0.1:5432/app"
npm start

预期输出

text
服务开始监听 3000 端口。
实际日志格式取决于项目实现;进程不应立即退出。

另开终端执行健康检查。

bash
curl -i http://127.0.0.1:3000/health

预期输出

text
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 后重新执行本课的干净构建,最容易复现真实部署环境。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

构建前端与后端应用

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通