React / 系统课时
搭建前后端项目骨架
搭建前后端项目骨架
本课搭建一个可同时启动的全栈开发骨架:React 18 前端通过 Vite 运行,Express 与 TypeScript 提供后端接口,MySQL 负责持久化。完成后,浏览器能够访问健康检查并确认数据库连接正常。
学习目标
- 初始化前端、后端和根工作区目录
- 用统一环境变量连接浏览器、API 与数据库
- 建立一条可验证的本地开发启动链路
规划工作区结构
项目采用 npm workspaces 管理两个应用。apps/web 只保存浏览器代码,apps/api 只保存服务端代码;根目录负责统一脚本和环境变量示例。
task-manager/
├─ apps/
│ ├─ web/
│ └─ api/
├─ .env.example
├─ .gitignore
└─ package.json运行时请求链路是:浏览器访问 Vite,Vite 把 /api 请求代理到 Express,Express 再连接 MySQL。数据库账号只由后端读取,前端只能读取带 VITE_ 前缀的公开变量。

初始化前端与后端
在空目录中执行以下命令。命令使用 Vite 创建 React TypeScript 项目,并为 API 安装 Express、MySQL 驱动和开发期类型依赖。
mkdir task-manager
cd task-manager
npm init -y
npm create vite@latest apps/web -- --template react-ts
cd apps/web
npm install react@18 react-dom@18
npm install -D @types/react@18 @types/react-dom@18
cd ../..
node -e "require('fs').mkdirSync('apps/api/src', { recursive: true })"
cd apps/api
npm init -y
npm install express cors dotenv mysql2
npm install -D typescript tsx @types/node @types/express @types/cors
cd ../..
npm install -D concurrently
node -e "const fs=require('fs'); console.log(fs.existsSync('apps/web/package.json') && fs.existsSync('apps/api/package.json') ? 'skeleton ready' : 'skeleton missing')预期输出
skeleton ready依赖安装过程中的日志会随 npm 版本和缓存状态变化,最后一行应为 skeleton ready。命令还会把前端运行时固定在 React 18,并生成 apps/web/package.json 与 apps/api/package.json。
配置工作区与启动脚本
把根目录 package.json 改为下面内容。工作区脚本会并行启动前端和后端,避免分别进入两个目录运行命令。
{
"name": "task-manager",
"private": true,
"workspaces": [
"apps/web",
"apps/api"
],
"scripts": {
"dev": "concurrently -n web,api \"npm --workspace apps/web run dev\" \"npm --workspace apps/api run dev\""
},
"devDependencies": {
"concurrently": "^9.0.0"
}
}把 apps/api/package.json 中的脚本和模块类型调整为下面内容;依赖版本保留安装命令实际写入的值。
{
"name": "api",
"private": true,
"type": "module",
"scripts": {
"dev": "tsx watch src/server.ts",
"typecheck": "tsc --noEmit"
}
}片段示例:第二段只展示需要人工合并的字段,不能直接覆盖安装后完整的 apps/api/package.json。合并后执行 npm install,确保工作区锁文件与两个子项目一致。
统一环境变量边界
根目录创建 .env.example。前端公开变量必须使用 VITE_ 前缀;数据库账号不带该前缀,因此不会被 Vite 注入浏览器代码。
PORT=3000
VITE_API_BASE_URL=/api
DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=task_manager
DB_USER=task_app
DB_PASSWORD=change_me这是配置文件示例,不直接执行。将其复制为 .env 后填写本机数据库信息,并把 .env 加入 .gitignore,只提交 .env.example。
配置 apps/web/vite.config.ts,让 Vite 从根目录读取公开变量,并代理 API 请求。
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
export default defineConfig({
plugins: [react()],
envDir: '../../',
server: {
port: 5173,
proxy: {
'/api': {
target: 'http://localhost:3000',
changeOrigin: true
}
}
}
});生效后,浏览器请求 /api/health 时不会发生跨域跳转,而是由 Vite 开发服务器转发给后端。生产环境仍应由反向代理或同域部署接管该路径。
实现后端健康检查
创建 apps/api/tsconfig.json。
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"outDir": "dist"
},
"include": [
"src"
]
}创建 apps/api/src/server.ts。启动时加载根目录 .env,健康检查通过 SELECT 1 验证数据库,而不是只返回固定字符串。
import cors from 'cors';
import dotenv from 'dotenv';
import express from 'express';
import mysql from 'mysql2/promise';
import { resolve } from 'node:path';
dotenv.config({ path: resolve(process.cwd(), '../../.env') });
const app = express();
const port = Number(process.env.PORT ?? 3000);
const pool = mysql.createPool({
host: process.env.DB_HOST,
port: Number(process.env.DB_PORT ?? 3306),
database: process.env.DB_NAME,
user: process.env.DB_USER,
password: process.env.DB_PASSWORD,
connectionLimit: 5
});
app.use(cors());
app.use(express.json());
app.get('/api/health', async (_request, response) => {
try {
await pool.query('SELECT 1');
response.json({ status: 'ok', database: 'connected' });
} catch {
response.status(503).json({
status: 'error',
database: 'disconnected'
});
}
});
app.listen(port, () => {
console.log(`API listening on http://localhost:${port}`);
});预期输出
API listening on http://localhost:3000这段代码可独立运行,但要求 MySQL 已启动、目标数据库与账号已创建,并且根目录 .env 中的连接信息正确。
连接 React 页面并验证
替换 apps/web/src/App.tsx。组件在首次渲染时调用健康检查,并把结果直接显示在页面上。
import { useEffect, useState } from 'react';
type HealthResponse = {
status: string;
database: string;
};
export default function App() {
const [message, setMessage] = useState('正在连接后端...');
useEffect(() => {
const loadHealth = async () => {
const baseUrl = import.meta.env.VITE_API_BASE_URL ?? '/api';
const response = await fetch(`${baseUrl}/health`);
if (!response.ok) {
throw new Error(`HTTP ${response.status}`);
}
const data = (await response.json()) as HealthResponse;
setMessage(`API ${data.status},数据库 ${data.database}`);
};
loadHealth().catch((error: unknown) => {
const reason = error instanceof Error ? error.message : '未知错误';
setMessage(`连接失败:${reason}`);
});
}, []);
return (
<main>
<h1>Task Manager</h1>
<p>{message}</p>
</main>
);
}预期结果
Task Manager
API ok,数据库 connected复制环境变量并启动两个应用。
node -e "require('fs').copyFileSync('.env.example', '.env')"
npm install
npm run dev预期输出
[api] API listening on http://localhost:3000
[web] Local: http://localhost:5173/浏览器打开 http://localhost:5173 后,页面应显示“API ok,数据库 connected”。如果页面显示连接失败,先检查 .env 的数据库账号,再直接访问 http://localhost:3000/api/health 判断问题位于 API 还是 Vite 代理。