Node.js+Vue+ThinkPHP搭建个人健康档案管理系统全栈实践

做个人健康档案管理系统，技术栈把 Node.js、Vue 和 ThinkPHP 撮合到一起，乍看有点混搭，但真落地跑通之后你会发现，这套组合其实是拿各自的舒适区干活：Vue 负责界面交互，ThinkPHP 出接口速度快、写业务顺手，Node.js 夹在中间既能当开发工具链的运行时，又能做资源代理或者文件预处理的服务层。这篇文章把我从环境搭建、项目初始化到核心模块实现、再到填坑排查的完整过程整理出来，适合拿来做毕业设计、中小型机构内部健康管理系统，或者单纯想练全栈的同学参考。

先说清楚这个系统到底做什么：用户注册登录后维护自己的健康档案，包括基础信息、体检报告、血压血糖等日常指标、既往病史和用药记录；管理员端可以审核档案、查看统计数据、按条件检索用户。整个系统是前后端分离架构，前端 Vue 单页应用，后端 ThinkPHP 提供 RESTful 接口，Node.js 在开发阶段承担构建工具链，部署后还可以作为静态资源服务器和 API 转发网关。下文按我实际开发的顺序来写，每一步都给到可直接抄的参数、代码和避坑点。

1. 系统设计与技术选型思路

1.1 为什么是 Node.js + Vue + ThinkPHP 三件套

这个组合看起来有点"跨圈"，很多人第一反应是：健康档案系统用 PHP 一套搞完不就行了？确实可以，但加了 Vue 和 Node.js 之后体验完全不一样。

Vue 的介入解决了两个问题：一个是页面交互复杂度。健康档案的数据录入不是简单表单，体检报告要分项展示、血压血糖变化要动态绘图、档案列表要支持多条件筛选和分页，这些操作在传统多页应用里每步都要刷新页面，做了前后端分离之后流畅度提升非常明显。另一个是开发效率，Vue 的单文件组件把 HTML、CSS、JS 收在一起，改一个模块不需要在十几个 PHP 文件之间反复跳转，组件复用也让档案列表、指标趋势这类页面可以快速堆出来。

ThinkPHP 的角色很好理解：它能快速出接口、带现成的模型操作和验证器，对于个人健康档案这种以增删改查为主、附带状态流转的业务，PHP 的开发速度确实快。尤其 ThinkPHP 6/8 的控制器中间件、资源路由、验证器这几板斧，写 RESTful API 非常顺手，我在本文里用的是 ThinkPHP 8，但 6 也完全适用，代码差异不大。

Node.js 在这里不是主角，但又是不可缺少的配角。开发阶段前端启动、依赖安装、构建打包全走 Node.js 生态；部署阶段我用它做了一件事——静态资源服务和 API 反向代理，让 Vue 打包产物和 ThinkPHP 接口跑在同一个端口下，避免跨域问题。这是因为 Node.js 的 http-proxy-middleware 做转发非常方便，十几行代码就能把 /api 请求转给 ThinkPHP 处理，比自己配 CORS 省心得多。如果你不想在服务器上额外跑一个 Node 进程，也可以直接用 Nginx 做同样的事，但本项目的定位是"一个命令启动整个系统"，Node.js 作为网关更符合这个目标。

1.2 核心模块拆解与数据库设计

个人健康档案系统按角色拆模块，首先是用户端：

• 注册登录、密码找回
• 个人基础信息维护（姓名、性别、出生日期、血型、身高体重）
• 健康档案管理：体检报告上传与查看、既往病史、过敏史、手术史
• 日常指标记录：血压、血糖、心率、体重，支持按时间范围查询和趋势图
• 用药提醒：记录药品名称、剂量、用药时间，到点提醒（前端轮询实现）

然后是管理员端：

• 用户档案审核与状态管理（正常/锁定）
• 档案数据统计：按年龄段、性别、地区分布
• 异常指标预警：血压超过阈值时标记高危

数据表设计我列一下核心结构，这是系统的地基，浪费一点篇幅是值得的：

user 表存账号和角色，role 字段区分 1（普通用户）和 2（管理员）。profile 表存用户档案详情，与 user 一对一。medical_record 表是体检记录，包含 user_id、record_date、hospital_name、conclusion（体检结论），附件路径存在附件表里。health_metric 表存日常指标，核心字段是 metric_type（blood_pressure / blood_sugar / heart_rate / weight）、metric_value（存 JSON 字符串，血压存收缩压和舒张压两个值）、recorded_at 时间戳。attachment 表统一管理上传的图片和报告文件，belong_type 和 belong_id 做多态关联，这样用户头像、体检报告图片、PDF 文件都可以复用同一张表。

建表时有个细节容易忽略——一定要用 utf8mb4 字符集，健康档案里可能出现生僻字人名的场景，亲测 utf8 遇到生僻姓直接报 Incorrect string value，换 utf8mb4 之后天下太平。另外 metric_value 用 JSON 字段而不是拆成多列，灵活性高很多，血压存 {"systolic":120,"diastolic":80}，血糖存 {"fasting":5.6,"postprandial":7.8}，后期想加指标类型不用改表结构。

数据库设计完了，技术架构就清晰了：Vue 页面发请求到 Node.js 网关，网关按路径前缀转发到 ThinkPHP 控制器，控制器调模型查库再返回 JSON。下面从环境搭建开始，先解决"跑不起来"的问题。

2. 基础环境配置与项目初始化

2.1 Node.js 安装与环境变量配置

Node.js 是前端项目的运行时基础，建议装 LTS 版本。N 官网下载 Windows 安装包，一路 Next 就行。安装完成后验证是否成功，打开命令行工具输入：

bash复制node -v
npm -v

能看到版本号说明安装成功。如果没有输出，大概率是环境变量没配好。默认安装路径是 C:\Program Files\nodejs，需要把这个目录加到系统变量 PATH 里。右键"此电脑" → 属性 → 高级系统设置 → 环境变量，在 Path 中确认是否已包含安装路径。我在一台备用电脑上遇到过装完后命令行里输入 node 报"不是内部或外部命令"，手动添加环境变量重启终端后解决。

Node.js 安装后第一件事是换 npm 镜像源，国内直连官方源装依赖非常痛苦，动不动超时。执行：

bash复制npm config set registry https://registry.npmmirror.com

验证是否生效：

bash复制npm config get registry

特别提示：如果你用 PowerShell 运行 npm 命令时报错 无法加载文件 ...\npm.ps1，因为在此系统上禁止运行脚本，这不是 npm 坏了，而是 PowerShell 默认执行策略禁止运行脚本文件。 解决办法是以管理员身份打开 PowerShell，执行：

powershell复制Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

然后选择 Y 确认。当然用 CMD 命令行工具就不会有这个限制。

2.2 Vue 项目创建与关键依赖安装

Vue 项目我用 Vite 构建，比起 Webpack 冷启动速度快了不是一星半点。创建命令是：

bash复制npm create vite@latest health-frontend -- --template vue

进入目录后安装项目依赖和运行需要的第三方库：

bash复制cd health-frontend
npm install
npm install vue-router@4 pinia axios element-plus echarts

这里逐个解释引入它们的原因：

• vue-router@4：Vue 3 配套路由，管理页面跳转
• pinia：状态管理，替代 Vuex，更简洁，TypeScript 支持好
• axios：HTTP 请求库，统一处理 API 调用和拦截器
• element-plus：UI 组件库，表格、表单、弹窗这些不用自己写
• echarts：数据可视化，画血压血糖趋势图

装完跑一遍 npm run dev，浏览器访问 http://localhost:5173，看到 Vite 欢迎页，前端骨架就搭起来了。

2.3 ThinkPHP 环境准备与项目创建

ThinkPHP 8 要求 PHP 8.0 以上，我用的是 PHP 8.2 + MySQL 8.0。PHP 环境不是本文重点，但有一个关键点要提：PHP 的 php.ini 里务必开启扩展 fileinfo、openssl、pdo_mysql，TP 的验证器、文件上传和数据库驱动都依赖它们。

安装 ThinkPHP 直接用 Composer：

bash复制composer create-project topthink/think health-server

项目创建后进入目录，复制 .env.example 为 .env，配置数据库连接。注意 TP 8 的配置读取方式，.env 文件里的配置会被框架自动加载并覆盖 config/database.php 的默认值：

ini复制APP_DEBUG = true
[APP]
DEFAULT_TIMEZONE = Asia/Shanghai

[DATABASE]
TYPE = mysql
HOSTNAME = 127.0.0.1
DATABASE = health_system
USERNAME = root
PASSWORD = your_password
HOSTPORT = 3306
CHARSET = utf8mb4

这里要提前在 MySQL 里建好数据库，命令行执行 CREATE DATABASE health_system DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;。然后启动看能否连通：

bash复制php think run -p 8000

浏览器访问 http://localhost:8000，看到欢迎页说明 TP 基础环境没问题。

2.4 Node.js 网关服务搭建

这是本项目组合的关键环节。我创建一个独立目录 server-gateway，用 Express 搭一个轻量网关：

bash复制npm init -y
npm install express http-proxy-middleware

核心思路：所有 /api 开头的请求转发到 TP 服务，其余路径返回 Vue 打包后的静态文件。开发阶段只保留代理功能，生产环境再加静态目录：

javascript复制// server.js
const express = require('express')
const { createProxyMiddleware } = require('http-proxy-middleware')
const app = express()

app.use('/api', createProxyMiddleware({
  target: 'http://127.0.0.1:8000',
  changeOrigin: true,
  pathRewrite: { '^/api': '' }
}))

app.listen(3000, () => console.log('Gateway running at http://localhost:3000'))

用 Node.js 做代理有个非常实际的好处：Vue 开发环境用 Vite 代理到网关，生产环境由网关提供静态资源，前端代码里的请求路径全程写 /api/... 开头，部署到任何环境都不需要因为域名或端口变化改代码，统一走网关这一条路。

3. ThinkPHP 后端接口实现要点

3.1 路由定义与控制器规划

ThinkPHP 8 的路由推荐使用注解或路由注册文件。个人健康档案系统的接口按模块划分，在 route/app.php 里集中注册：

php复制use think\facade\Route;

// 认证模块
Route::post('auth/register', 'Auth/register');
Route::post('auth/login', 'Auth/login');

// 档案模块（需要登录）
Route::group('profile', function () {
    Route::get('index', 'Profile/index');
    Route::post('update', 'Profile/update');
    Route::post('upload-avatar', 'Profile/uploadAvatar');
})->middleware(['auth']);

// 健康指标模块
Route::group('metric', function () {
    Route::get('list', 'Metric/list');
    Route::post('add', 'Metric/add');
    Route::delete('delete/:id', 'Metric/delete');
})->middleware(['auth']);

这里把需要登录的接口放到一个路由组里，统一挂 auth 中间件，比在每个控制器里手动校验会话省事得多。TP 的中间件实现在 app/middleware.php 注册全局中间件，认证中间件本身我放在 app/middleware/Auth.php：

php复制namespace app\middleware;

use think\facade\Cache;
use think\facade\Db;

class Auth
{
    public function handle($request, \Closure $next)
    {
        $token = $request->header('token');
        if (!$token || !Cache::get($token)) {
            return json(['code' => 401, 'msg' => '请先登录']);
        }
        $userId = Cache::get($token);
        $request->userId = $userId;

        $user = Db::name('user')->find($userId);
        if ($user['status'] != 1) {
            return json(['code' => 403, 'msg' => '账号已被锁定']);
        }
        return $next($request);
    }
}

Token 用的是简单的新鲜感不强的方案——登录后生成一个随机字符串存 Redis 或 TP 缓存，键名是 token，值是对应用户 ID，客户端每次请求把 token 放在 header 里。这个方案实现简单、可控性强，对个人健康档案这种中小型系统足够了。你要是想更严谨，可以换成 JWT，前端拦截器统一加 token 的逻辑不变。

3.2 登录注册与 Token 签发

注册逻辑需要注意密码不能明文存，TP 内置的 think\helper\Hash::make() 可以直接用：

php复制public function register()
{
    $data = request()->post();
    $validate = new \app\validate\UserValidate();
    if (!$validate->check($data)) {
        return json(['code' => 400, 'msg' => $validate->getError()]);
    }

    $data['password'] = Hash::make($data['password']);
    $data['create_time'] = time();
    $data['status'] = 1;

    $userId = Db::name('user')->insertGetId($data);
    return json(['code' => 200, 'msg' => '注册成功', 'data' => $userId]);
}

登录接口验证密码时用 Hash::check($inputPassword, $user['password'])。密码策略还要保证最小长度 6 位、字母数字结合，这些在验证器里做好，不要等到入库了再补救。

签发 token 用随机加盐方式：

php复制$token = md5($user['id'] . time() . uniqid());
Cache::set($token, $user['id'], 7200); // 2小时过期

用户登录后前端能拿到 { token, userInfo }，前端把 token 存到 Pinia 里并同步给 localStorage，请求拦截器自动带上。这快就构成了完整的认证链路。

3.3 健康指标接口与数据校验

健康指标模块的核心看起来是增删改查，真正要花心思的是数据校验和数值区间判断。血压值录入时必须区分收缩压和舒张压，血糖必须区分空腹和餐后。我的做法是在后端定义一个指标配置表：

php复制$rule = [
    'metric_type' => 'require|in:blood_pressure,blood_sugar,heart_rate,weight',
    'metric_value' => 'require|json'
];

这里容易踩坑：TP 验证器的 json 规则只能保证它是个合法 JSON 字符串，不能验证里面是否包含预期字段。所以我在验证后还要手动检查：

php复制$value = json_decode($data['metric_value'], true);
if ($data['metric_type'] == 'blood_pressure') {
    if (!isset($value['systolic']) || !isset($value['diastolic'])) {
        return json(['code' => 400, 'msg' => '血压数据缺少收缩压或舒张压']);
    }
    if ($value['systolic'] < 60 || $value['systolic'] > 250) {
        return json(['code' => 400, 'msg' => '收缩压数值异常']);
    }
}

数值范围校验表面看是在防数据异常，实际上是为后面的预警功能做准备。血压超过 140/90 就要标记高危，这个判断在后端做，不能让前端控制，因为用户可能绕过页面直接调接口。健康系统的数据安全靠后端兜底，前端只是体验层。

3.4 文件上传：体检报告和附件处理

体检报告上传走 ThinkPHP 的文件系统组件。TP 8 里用 think\facade\Filesystem 上传，配置 config/filesystem.php 指定本地磁盘（默认就是本地 storage 目录）：

php复制public function upload()
{
    $file = request()->file('file');
    if (!$file) {
        return json(['code' => 400, 'msg' => '未获取到上传文件']);
    }

    $validate = ['ext' => 'jpg,jpeg,png,pdf', 'size' => 20 * 1024 * 1024];
    try {
        $file->validate($validate);
        $saveName = (string) $file->store('report', 'public');
        return json(['code' => 200, 'msg' => '上传成功', 'data' => [
            'url' => '/storage/' . $saveName,
            'name' => $file->getOriginalName()
        ]]);
    } catch (\think\exception\ValidateException $e) {
        return json(['code' => 400, 'msg' => $e->getMessage()]);
    }
}

上传路径按 年/月/日期 归组，store('report', 'public') 会自动按日期分目录，避免一个目录塞太多文件导致系统变慢。上传类型限 jpg/png/pdf，档案系统里的报告可能是图片也可能是 PDF。还要注意 storage 目录需要软链接到 public/storage，TP 8 提供了命令自动生成：

bash复制php think storage

前端接上传接口直接用 Element Plus 的 el-upload 组件，action 指向 /api/upload，headers 带上 token。配置 on-success 回调里把返回的文件名存到表单数据中，随体检记录一起提交。

4. Vue 前端核心功能开发与实现

4.1 路由配置与登录守卫

前端路由在 src/router/index.js 里配置，路由表分公共路由和需要登录的路由：

javascript复制const routes = [
  { path: '/login', component: () => import('@/views/Login.vue') },
  { path: '/register', component: () => import('@/views/Register.vue') },
  {
    path: '/',
    component: () => import('@/layout/MainLayout.vue'),
    redirect: '/dashboard',
    children: [
      { path: 'dashboard', component: () => import('@/views/Dashboard.vue'), meta: { requiresAuth: true } },
      { path: 'profile', component: () => import('@/views/Profile.vue'), meta: { requiresAuth: true } },
      { path: 'record/list', component: () => import('@/views/medical/RecordList.vue'), meta: { requiresAuth: true } },
      { path: 'metric/list', component: () => import('@/views/metric/MetricList.vue'), meta: { requiresAuth: true } }
    ]
  }
]

路由守卫我放在 router.beforeEach 里，判断逻辑三段式：

javascript复制router.beforeEach((to, from, next) => {
  const token = localStorage.getItem('token')
  if (to.path === '/login') {
    token ? next('/') : next()
  } else if (to.meta.requiresAuth && !token) {
    next('/login')
  } else {
    next()
  }
})

有了路由守卫还不够，按钮级别的权限控制要用自定义指令或者 v-if 判断用户角色。管理员端可见的操作按钮（审核、用户管理）在渲染时判断 userInfo.role === 2，这样做防止普通用户看到入口。但注意这只是前端隐藏菜单，后端接口仍然要鉴权，我之前遇到有人通过控制台发请求直接删除记录的情况，就是因为前端隐藏了按钮、后端没加权限校验，这个教训很深刻。

4.2 Pinia 状态管理与请求封装

登录后的用户信息、token 不能只放在 localStorage 里裸用，Pinia 统一管理。src/store/user.js：

javascript复制export const useUserStore = defineStore('user', {
  state: () => ({
    token: localStorage.getItem('token') || '',
    userInfo: JSON.parse(localStorage.getItem('userInfo') || '{}')
  }),
  actions: {
    setLogin(token, userInfo) {
      this.token = token
      this.userInfo = userInfo
      localStorage.setItem('token', token)
      localStorage.setItem('userInfo', JSON.stringify(userInfo))
    },
    logout() {
      this.token = ''
      this.userInfo = {}
      localStorage.removeItem('token')
      localStorage.removeItem('userInfo')
    }
  }
})

axios 实例封装在 src/utils/request.js，统一设置 baseURL /api，请求拦截器加 token，响应拦截器处理业务状态码。这里有一个重要经验——响应拦截器要区分 status 和业务 code 两套校验：HTTP 状态码 200 只代表网络层面通了，业务 code 才是系统的返回值。拦截器里遇到 code 401 要清掉本地登录状态跳回登录页，遇到 500 要弹出错误提示而不是让用户面对空白页：

javascript复制service.interceptors.response.use(
  response => {
    const res = response.data
    if (res.code !== 200) {
      ElMessage.error(res.msg || '操作失败')
      if (res.code === 401) {
        userStore.logout()
        router.push('/login')
      }
      return Promise.reject(new Error(res.msg))
    }
    return res
  },
  error => {
    ElMessage.error(error.message || '网络异常')
    return Promise.reject(error)
  }
)

4.3 健康指标录入与趋势图展示

指标录入页面是健康档案系统最高频的交互场景。表单用 Element Plus 的 el-form 渲染，根据 metric_type 的变化动态切换字段：选血压就显示两个输入框（收缩压、舒张压），选血糖显示空腹/餐后两个输入框，选心率体重就一个输入框。这种动态表单体验远比固定模板好。

提交数据时需要把两个字段组装成 JSON 字符串再传给后端：

javascript复制const form = reactive({
  metric_type: 'blood_pressure',
  systolic: null,
  diastolic: null,
  fasting: null,
  postprandial: null,
  weight: null,
  recorded_at: new Date().toISOString()
})

function handleSubmit() {
  let metricValue = {}
  if (form.metric_type === 'blood_pressure') {
    metricValue = { systolic: form.systolic, diastolic: form.diastolic }
  } else if (form.metric_type === 'blood_sugar') {
    metricValue = { fasting: form.fasting, postprandial: form.postprandial }
  }
  // ...
}

趋势图用 ECharts 的折线图呈现。我从后端拉取某个时间区间的所有指标数据，前端按 recorded_at 升序排列，横轴是日期，纵轴是指标值：

javascript复制const chart = echarts.init(document.getElementById('trendChart'))
chart.setOption({
  xAxis: { type: 'category', data: dateList },
  yAxis: { type: 'value' },
  series: [{
    type: 'line',
    data: valueList,
    smooth: true,
    areaStyle: { opacity: 0.15 }
  }]
})

趋势图这里要提醒一件事：ECharts 实例在组件销毁时要调用 dispose()，不然多路由切换几次就会出现白屏或者内存持续上涨的情况。我在 onBeforeUnmount 里统一处理。

4.4 动态路由与管理员模块

管理员模块的页面在登录后才需要注册。用 Vue Router 4 的 addRoute 做动态路由，登录成功拿到用户角色后，判断是管理员再追加路由：

javascript复制if (userInfo.role === 2) {
  router.addRoute({
    path: '/admin',
    component: () => import('@/layout/AdminLayout.vue'),
    children: [
      { path: 'users', component: () => import('@/views/admin/UserManage.vue') },
      { path: 'stats', component: () => import('@/views/admin/Stats.vue') }
    ]
  })
  router.replace('/admin/users')
}

动态路由有坑，路由是"添加"不是"替换"，重复添加会报警告甚至覆盖原有配置。这个 bug 在热更新场景下非常容易触发，我现在习惯在登录流程里加一个 router.removeRoute 先把旧路由清掉再 add，或者在登出时重置路由。正常的做法是：维护一个 constantRoutes 和 asyncRoutes 数组，登录后过滤出用户权限内的路由用 addRoute 注册，切换账号时先清空之前的动态路由再重新注册。

4.5 体检报告展示：PDF 与图片适配

体检报告可能是 PDF，也可能是多张图片。图片展示简单，直接用 <el-image> 解决。PDF 在 Vue 里显示就要注意了，不同浏览器对 <embed> 和 <iframe> 渲染 PDF 的支持不一样，Chrome 可以直接显示，但同样代码在部分国产浏览器或低版本浏览器上就变成下载而不是预览。

我的做法是用 pdfjs-dist 的 view 模式，把 PDF 渲染成 canvas 显示在抽屉里，统一各浏览器体验。安装：

bash复制npm install pdfjs-dist@3.11.174

核心思路是读取 PDF url，pdf.getPage(i) 循环渲染到 canvas。具体代码不展开，这里提醒关键点：pdfjs-dist 版本差异很大，新版本换了 worker 加载方式，加 pdf.js worker 的配置时按版本文档来，别照抄老代码，经常装完跑起来报 Failed to fetch dynamically imported module，八成是 worker 路径没配对。

如果项目场景是用户上传的健康宣教视频，可能会涉及 m3u8 格式。Vue 播放 m3u8 可以用 hls.js，用法几行：

javascript复制npm install hls.js

if (Hls.isSupported()) {
  const hls = new Hls()
  hls.loadSource(videoUrl)
  hls.attachMedia(videoElement)
}

但注意 iOS 的 Safari 原生支持 m3u8，不需要 hls.js，所以代码要写成 if (video.canPlayType('application/vnd.apple.mpegurl')) 优先走原生播放。这个双轨判断在接 IPC 摄像头片段时很实用。

5. 常见问题排查与踩坑实录

5.1 npm.ps1 禁止运行脚本的根治方案

这个报错的热搜度极高，我几乎每个新同事入职都会遇到。背景是 Windows 下 npm 提供了 npm.cmd 和 npm.ps1 两个可执行文件，PowerShell 默认执行策略是 Restricted，不允许运行 .ps1 脚本。报错内容通常带着完整路径：

code复制npm : 无法加载文件 d:\program files\nodejs\npm.ps1
因为在此系统上禁止运行脚本

两种解决办法，按你偏好选：

方案一（推荐，全局生效）：管理员权限打开 PowerShell，执行 Set-ExecutionPolicy RemoteSigned。这个策略允许本机脚本运行、要求远程下载的脚本必须有签名，兼顾安全和便利。

方案二（不影响全局）：每次改用 CMD 而不是 PowerShell 执行 npm 命令。CMD 调用 npm.cmd，完全绕开 .ps1 这条链。

还有一个隐藏问题：node 命令在 PowerShell 里没问题、npm 就有问题，说明 Node.js 只装了 exe 主程序，npm 的全局脚本没进 PATH，或者 %APPDATA%\npm 目录没加到环境变量。这种情况直接检查 C:\Users\你的用户名\AppData\Roaming\npm 是否存在、PATH 里有没有它。

5.2 跨域问题的三种解决路径

前后端分离架构，跨域是绕不过去的话题。本项目用 Node.js 网关代理以后，前端页面和 API 请求是同域（都是 http://localhost:3000），跨域问题没有了，这是最推荐的方式，因为它等于把后端接口对外隐藏了。

但如果你不用网关，直接开发时 Vite 代理或让前端请求 TP 服务，就会遇到跨域。TP 后端要在中间件里加 CORS 头：

php复制header('Access-Control-Allow-Origin: *');
header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE');
header('Access-Control-Allow-Headers: token, Content-Type');

这还不够，如果请求带 Content-Type: application/json，浏览器会先发一个 OPTIONS 预检请求。TP 默认路由不会响应 OPTIONS，所以我需要在全局中间件里拦截：

php复制if (request()->method() == 'OPTIONS') {
    return response('', 204);
}

注意 Access-Control-Allow-Headers 里必须包含 token，很多人 CORS 配置了却没加这一项，前端头顶的鉴权头被浏览器拦截，API 返回 200 但业务里永远拿不到用户身份，这种 bug 排查起来很迷惑。

5.3 Vue 路由刷新 404 的坑

用 createWebHistory 模式开发完，打包部署到网关服务上，很多人会遇到"页面内跳转正常，浏览器刷新或直接输 URL 就 404"的问题。原因是 Vue 路由模式用的是 History API，刷新时浏览器会请求真实 URL，Node.js 网关找不到对应资源，返回 404。

解决方式有两种。简单粗暴是改用 createWebHashHistory，URL 里带 #，刷新时不会向服务器发请求，但浏览器地址栏丑一点。对健康档案系统这类内部系统，也不影响。更专业的是在 Node.js 网关里加一个 history 回退中间件，所有非 /api 的 GET 请求都回退到 index.html：

javascript复制const path = require('path')
const fs = require('fs')

app.use((req, res, next) => {
  if (req.path.startsWith('/api')) {
    return next()
  }
  const filePath = path.join(__dirname, 'dist', req.path)
  if (fs.existsSync(filePath)) {
    return next()
  }
  res.sendFile(path.join(__dirname, 'dist', 'index.html'))
})

这个方案还有一个好处，SPA 的任意深层链接都可以分享给其他人直接打开对应页面，不至于落到 404 页面。

5.4 文件上传相关的坑：超限、格式、路径权限

健康档案系统文件上传场景多，踩过的坑也最杂。整理一张常见问题速查表：

另外文件上传校验要确认 enctype="multipart/form-data"，用 axios 的 FormData 对象时不要手动设置 Content-Type，axios 会自动加上带 boundary 的 multipart 类型。我之前为了显式加 application/json 上传文件导致接口一直收不到数据，这类问题查半天最后发现请求头格式错。

5.5 Node.js 安装后偶发问题的快速修复

Node.js 环境偶尔会出一些莫名问题，比如 npm install 装到一半报 Unexpected end of JSON input，这是缓存损坏。清缓存重装：

bash复制npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Windows 上如果 rm -rf 不好用就用命令行 rd /s /q node_modules。再比如 Node.js 版本升到 18 之后某些老包不兼容、编译报错，优先把项目目录下的 node_modules 全删了重装，不要想着一个个包去修。遇到 node-gyp 编不过的模块（比如 node-sass），用 npm 里新生态的 sass 包替代，语法几乎兼容。

还有 ubuntu 环境装完 node 后 node -v 正常但 npm -v 报错，常见原因是 PATH 里有多个 node 版本或者 /usr/bin/node 和 /usr/local/bin/node 冲突。先执行 which -a node 看一遍全路径，去掉冲突版本。

6. 实操心法与方案扩展

个人健康档案管理系统做完一轮，我最有感触的是这种多技术栈协同项目最重要的其实不是某个具体功能，而是边界划分。Vue 管交互、ThinkPHP 管业务逻辑和数据、Node.js 管转发和静态资源，三层之间通过 HTTP + JSON 做契约，每一层可以独立测试、独立升级。开发时我经常只启动 TP 服务用 Postman 测接口，前端 mock 数据调页面，两边并行推进互不阻塞，最后联调的效率非常高。

扩展方向也有几条现成的思路：加体检报告 OCR 解析，让系统自动提取报告中的指标数值归类入库，Node.js 在这里可以承担异步任务调度的角色；加健康建议推送，根据指标趋势和阈值判断给出动态建议；加微信小程序端，小程序复用后端 API，前端要处理的只是登录 code 换 token 的问题。框架层面的边界保持不变，新增功能都是往模块里塞。

最后分享一个小技巧，我在部署这套系统时用 Node.js 的 pm2 同时守护网关和必要服务，配置一个 ecosystem.config.js 就能一键拉起整套环境。开发调试时改完后端 PHP 代码不需要重启服务，改完 Vue 代码会热更新，实测下来这套组合在中小型系统中的稳定性是够用的。个人健康档案系统的价值不在于功能多少，在于数据持续积累后能真正帮助用户了解和改善健康状况，这是我认为这套代码最值得打磨的地方。