企业官网建设流程全解析

做考研学习分享平台这个项目，一开始我是不太想把两个PHP框架放进同一个系统里的。但真正把Vue 3、ThinkPHP和Laravel协同一套前后端分离架构跑通之后，我发现这个组合反而是学习资料分享、视频课程和社区互动这类业务最适合的方案。Vue负责桌面端、后台管理、手机端H5的多端复用，ThinkPHP承担用户中心和资料模块的快速交付，Laravel则在中间件、队列、内容审核与文件处理上撑起复杂服务。这个项目解决的核心问题是：考研资料分散、经验内容碎片化、下载与审核流程不透明，平台同时覆盖资料管理、在线播放、积分体系和经验交流，适合正在做毕业设计的学生，也适合想快速搭建垂直教育社区的技术团队参考。

整个开发过程中绕了不少弯，尤其是双框架共存时的路由分发、CORS跨域、JWT鉴权、m3u8视频播放、Storage PDF预览这些环节，每一个都踩过坑。下面我会按“架构设计 -> 功能拆解 -> 关键实现 -> 问题排查”的顺序，把整个平台的思路和可复现方案完整写出来。

1. 项目整体设计与技术选型：为什么把 Vue、ThinkPHP、Laravel 放在一起

1.1 从 ThinkPHP 起步到引入 Laravel 的演进逻辑

这个项目刚开始并没有考虑双框架。考研学习分享平台早期的核心需求很简单：用户注册登录、上传资料、后端做基础管理，用ThinkPHP 6.0.12 LTS开发效率很高，它入口清晰、ORM直观、中文文档完善，适合团队里熟悉国内PHP生态的开发者快速上手。

但随着功能列表越拉越长，几个问题开始暴露：

• 内容审核、下载权限、操作日志、接口限流这些横切逻辑越来越多，需要一套更成熟的中间件管道；
• 视频转码、邮件通知、积分异步结算这类任务需要队列支持；
• 前后端分离之后，API资源返回格式、异常统一处理要做到更规范。

Laravel 的中间件实现原理本质上是一个管道模式，请求按顺序进入多个中间件，每个中间件负责一个关注点，处理完再传递给下一个，最后到达控制器。这种设计在统一鉴权、日志、CORS、权限校验时非常顺手。所以我把平台拆成两大部分：ThinkPHP继续承担用户中心、资料上传下载、积分系统和基础管理接口；Laravel则负责视频转码任务、内容审核流程、笔记社区互动、消息通知这些更偏服务化的模块。

双框架共用同一个MySQL库，Redis作为缓存和队列驱动，Nginx层按URL前缀分发流量。/api/tp开头的请求走ThinkPHP，/api/lar开头的请求走Laravel，前端Vue应用的axios请求基址根据业务模块动态选择。这套架构看起来有点重，但实际部署时每个框架都是独立入口，互不干扰，出问题也容易定位。

1.2 前端为什么用 Vue，以及版本选型的取舍

考研学习分享平台不是纯内容展示站，它有大量交互：搜索联想、资料列表分页、视频播放进度记录、帖子评论、后台表格操作。Vue这种响应式组件框架非常适合这类场景，把页面拆成组件后，前台门户、个人中心、管理后台可以复用大量代码。

版本选型上，我优先推荐Vue 3搭配组合式API。组合式API的逻辑复用能力对复杂页面帮助很大，比如视频播放器的进度上报逻辑、文件上传的分片逻辑、Token刷新逻辑都可以抽成独立的use函数。项目当时的快速实现采用了选项式API，对于团队习惯和快速迭代也更友好。UI组件库选择Ant Design Vue，表格、表单、布局组件比较全面，后台管理页开发速度能提升不少。

脚手架选择上，Vite明显优于Vue CLI，开发服务器启动和热更新速度差距很大，尤其是项目组件数量增加后，Webpack冷启动可能要等几十秒，Vite开发环境几乎秒开。Vue常用生态我列一下，后面实操都会用到：

• 路由：Vue Router 4，负责动态路由、子路由和路由守卫；
• 状态管理：Pinia，替代Vuex，逻辑更简洁；
• HTTP请求：Axios封装请求/响应拦截器；
• 视频播放：hls.js或video.js播放m3u8流；
• 富文本/Markdown：md-editor-v3配合DOMPurify做安全过滤。

1.3 整体架构与请求链路

整个系统请求链路的最终形态是这样的：

用户浏览器 -> CDN/Nginx静态资源（Vue打包后的dist目录） -> Nginx反向代理 -> /api/tp前缀 -> ThinkPHP6的public目录；/api/lar前缀 -> Laravel的public目录，遇到上传文件或生成的静态资源则直接访问Storage目录。

认证统一走JWT，ThinkPHP侧使用firebase/php-jwt签发和校验Token，Laravel侧使用tymon/jwt-auth，两边校验同一套密钥，这样用户登录一次，两个框架都能识别，不需要各自维护Session。前端axios拦截器统一从localStorage取Token，加到Authorization头里，后端中间件统一解析并注入当前用户信息。

提示：设计双框架架构时，最忌讳两边各自维护用户会话。一开始就把Token生成规则、过期时间、密钥统一好，后面日常开发能省掉大量联调成本。

2. 平台核心功能拆解：从用户体系到资料分享

2.1 用户体系：多角色权限与学生身份核验

考研平台天然有多角色需求：普通考生、学长学姐（内容贡献者）、管理员。普通考生可以看到资料列表、免费资源、经验帖；学长学姐可以上传资料、发布经验帖；管理员负责审核、用户管理、内容下架。

用户注册不再只用用户名密码，增加了学校邮箱或学号校验。注册时提交学校、专业、考研年份，后台根据学号规则做基本格式校验，正式内容发布前需要完成身份信息审核。这个流程能大幅减少垃圾注册。

前端路由守卫做按钮级和页面级权限控制，beforeEach里根据用户角色过滤路由表，Vue Router支持动态添加路由，后台可以控制不同角色看到哪些菜单。后端再做一层接口级校验，防止绕过前端直接调用接口。ThinkPHP侧我写了自定义中间件检查JWT和角色，Laravel侧利用自带的auth中间件配合自定义checkPermission中间件，逻辑清晰。

积分规则属于典型业务计算。资料下载消耗积分，签到送积分，资料被下载获得积分。我规定每份资料按分类和大小设置积分价格，下载扣减，作者获得80%积分分成。积分扣减必须用事务和行锁，防止并发请求导致用户积分变负数。ThinkPHP中使用Db::transaction包裹积分扣减和下载记录插入，Laravel中使用DB::transaction。

2.2 资料与笔记分享：文件上传、预览与下载

资料模块是考研学习分享平台的压舱石。上传流程分为几步：

1. 前端选文件后先计算MD5，发送给后端检查是否已存在，服务器做秒传判断；
2. 大文件按分片上传，前端切分文件，每个分片携带唯一上传ID和分片序号；
3. 后端接收分片，全部完成后触发合并任务；
4. 合并完成后生成文件记录，写入资料表，进入待审核状态。

PDF预览问题这个项目里出现过典型场景：Laravel的Storage磁盘存储文件后，如果用Storage::response($path)直接返回PDF流，前端通过window.open打开时经常遇到CORS报错或Content-Type不对。我的解决方式是单独写一个预览路由，通过控制器读取文件流并设置正确的Content-Type: application/pdf和Access-Control-Allow-Origin响应头，前端iframe直接指向这个带签名参数的路由。

资料审核通过后，管理员可以调整展示状态、推荐位、积分价格。下载时后端会校验用户当前积分、是否重复下载，通过后生成带时间戳的有效下载链接，过期自动失效，避免资源被爬虫批量抓取。

2.3 视频课程与m3u8播放

考研平台最费功夫的是视频课程模块。最初直接放MP4，用户带宽不够时卡顿严重，拖动进度条要等很久。后来全面转向HLS协议，也就是m3u8流媒体方案。

m3u8的基本原理很简单：把完整视频切成很多小段的TS文件，生成一个索引文件（.m3u8），播放器读取索引按顺序加载TS片段。这样首屏加载快、支持码率自适应、进度条拖动更流畅。

后端转码流程是：

1. 原视频上传到临时目录；
2. 使用ffmpeg转码生成HLS切片，每个切片设置在4到6秒；
3. 同时生成多码率版本，方便不同带宽用户自动切换；
4. 转码完成后将m3u8和ts文件存到可公开访问的存储路径；
5. 前端用hls.js播放，并定期上报播放进度，用户下次观看可以续播。

切片时长选择有讲究。切片太长首屏延时大，切片太短会导致ts文件数量过多、请求频繁。实测下来，6秒切片配合GOP关键帧对齐，播放流畅度和加载速度最均衡。转码命令示例：

ffmpeg -i input.mp4 -codec:v libx264 -codec:a aac -hls_time 6 -hls_list_size 0 -hls_segment_filename "output_%03d.ts" output.m3u8

前端播放组件核心逻辑如下：

import Hls from 'hls.js'; function initPlayer(videoEl, m3u8Url) { if (Hls.isSupported()) { const hls = new Hls({ enableWorker: true }); hls.loadSource(m3u8Url); hls.attachMedia(videoEl); return hls; } }

组件销毁时必须手动调用hls.destroy()，否则播放器实例会残留，切页面后视频还在后台拉流，内存和带宽都被白白耗掉。

2.4 经验分享与帖子互动：防XSS与搜索方案

经验交流模块包括经验帖、评论区、点赞收藏。这块业务本身不复杂，但内容安全必须重视。前端用v-html渲染后端返回的HTML是高风险操作，XSS攻击防不胜防。我建议让用户统一用Markdown语法发文，前端使用Markdown渲染器，并对渲染后的结果做DOMPurify过滤，只保留白名单标签和属性。

搜索这块，资料数量在几万条以内时，直接SQL LIKE匹配标题和标签就够了，加上索引和分页，响应速度在可接受范围。如果后期数据量涨上去，再考虑接入Meilisearch或Elasticsearch，现在过早引入搜索引擎反而增加部署成本。

3. 前后端分离的关键实现：鉴权、中间件、文件和播放

3.1 API 设计与 Axios 请求拦截封装

前后端分离后，API设计直接决定双方协作效率。我的实践是所有接口遵循RESTful风格，资源用名词复数，动作尽量用HTTP方法表达，错误统一返回{ code, message, data }结构。

Axios实例统一封装，关键逻辑有四点：请求拦截器添加Token、响应拦截器处理401自动刷新Token、针对双框架基址做模块化配置、上传下载的进度回调透传。核心代码参考：

const service = axios.create({ baseURL: import.meta.env.VITE_API_BASE, timeout: 15000, }); service.interceptors.request.use((config) => { const token = localStorage.getItem('token'); if (token) { config.headers.Authorization = 'Bearer ' + token; } return config; }); service.interceptors.response.use( (response) => { const res = response.data; if (res.code === 401) { // 刷新 token 并重放请求 return refreshToken().then(() => { config.headers.Authorization = 'Bearer ' + localStorage.getItem('token'); return service(config); }); } return res; }, (error) => { return Promise.reject(error); } );

3.2 ThinkPHP 侧实操：SQL 监听、ORM 和版本兼容问题

ThinkPHP 里的SQL监听是我强烈建议从一开始就做好的功能。排查接口慢、死锁、SQL注入问题时，能看到完整SQL语句会省很多时间。监听逻辑推荐放在全局中间件或服务提供者中注册。

ThinkPHP 6中监听SQL的代码可以写在app/middleware.php注册一个全局中间件，或者直接在应用的公共common.php里注册数据库事件：

use think\facade\Db; Db::listen(function ($sql, $time) { // 打印或写入日志 trace('[SQL] ' . $sql . ' 耗时: ' . $time . 's', 'sql'); });

这种监听方式只要请求周期内执行了任何SQL操作，都会通过事件回调输出，开发调试极其方便。生产环境可以改成慢查询日志，超过500毫秒的SQL单独记录。

版本兼容这块，我看到很多人还在问ThinkPHP 3.2兼容PHP 8的问题。3.2版本时代PHP还没有强类型约束，大量写法在PHP 8环境下会触发Deprecated甚至Fatal Error，不建议继续沿用。既然是新项目，直接上ThinkPHP 6.0.12 LTS版本更稳妥。另外，网上流传的很多ThinkPHP漏洞通告，基本都是旧版本的历史问题，升级到最新LTS版本并且关闭debug模式、严格过滤请求参数，安全隐患就能挡掉大部分。

3.3 Laravel 中间件实现原理与权限统一处理

Laravel中间件用起来很自然，但真正理解它的实现原理是在排查一次请求被反复加头后才认真的。Laravel通过Illuminate\Pipeline\Pipeline把请求传给多个中间件，每个中间件的handle方法接收请求和一个闭包$next，执行前置逻辑后调用$next($request)，再把响应返回。你可以理解为请求像传接力棒一样，层层进入，再层层返回。

我用这个机制做了三件统一的事情：

• JWT鉴权中间件：解析Token，设置全局当前用户；
• 权限校验中间件：检查当前用户可以访问的资源；
• CORS跨域中间件：统一给响应加跨域头。

CORS中间件顺序必须注意，它要在路由匹配阶段就响应OPTIONS预检请求，否则跨域请求会被浏览器拦截：

public function handle($request, Closure $next) { $response = $next($request); $response->header('Access-Control-Allow-Origin', '*'); $response->header('Access-Control-Allow-Methods', 'GET, POST, PUT, PATCH, DELETE, OPTIONS'); $response->header('Access-Control-Allow-Headers', 'Content-Type, Authorization'); if ($request->getMethod() === 'OPTIONS') { return response('', 204); } return $response; }

Access-Control-Allow-Headers里如果没有Authorization，前端携带Token的请求会被浏览器拦截，这个坑非常隐蔽，表现为接口在Postman里正常、浏览器里却报CORS错误。

3.4 文件与存储：本地磁盘与对象存储的抽象切换

资料、封面图、视频切片、PDF文件会占用大量磁盘空间。项目初期本地磁盘够用，但上线一段时间后肯定要向对象存储迁移。代码从一开始就不要写死存储路径。

ThinkPHP 6和Laravel都提供了文件系统抽象，可以用统一的Storage门面操作本地磁盘或云存储，切换时只需要改配置。我的建议是：

• 用户上传文件统一走应用层接口，控制器不直接写move()或store()，而是封装一个FileService；
• 文件存储路径按业务分类，如uploads/avatar、uploads/material、uploads/video；
• 对外暴露的URL统一经过签名，签名带过期时间，过期后返回403；
• 视频切片文件数量多，单独走CDN或对象存储，不建议和大文件混在同一个磁盘分区。

3.5 表格导出与页面响应：前端开发中容易翻车的两个细节

典型问题是“Vue对象赋值页面不变”。这个本质上是响应式丢失的问题，Vue 2里直接给对象新增属性不能触发视图更新，需要用$set；Vue 3使用Proxy后新增属性可以响应，但如果你替换的是深层嵌套对象，引用变化没正确触发，也会出现页面不刷新。处理方式非常直接：更新数据时整体替换目标对象或数组，不要试图修改原引用内部属性。比如表格数据用list.value = newList，而不是在list.value上做push之后以为Vue会自动感知多层嵌套变化。

另一个高频需求是“多个表格导出一个Excel”。前端可以拿到多个表格的数据后用SheetJS拼接多个sheet，或者使用exceljs做更复杂的样式控制，然后生成Blob对象下载。关键点是导出大文件时避免同步阻塞UI，建议放到异步任务里，并提示用户等待。

4. 实操中的典型问题与排查速查

4.1 前端环境搭建和路由配置的坑

很多人在Vue环境配置上花了不少时间。Vite创建项目的命令很简单，npm create vite@latest，但后续依赖安装容易遇到版本冲突。Node版本建议锁定18以上，npm或pnpm随便选，关键是项目里所有依赖要统一版本锁文件，避免团队成员拉代码后装出不同依赖树，难以复现问题。

路由配置里，最容易出问题的是子路由和路由参数。子路由要注意组件路径不能加/，否则会被当成根路径匹配；query参数刷新页面后还在，但如果你放到params里刷新就丢了。动态路由常用在权限菜单，后端返回菜单结构，前端用addRoute注册，这个过程中必须保证路由name唯一，否则重复注册会警告甚至异常。

4.2 后端鉴权、跨域和播放器问题排查

实际项目里最折磨人的还是跨域和播放器问题。我把几个典型问题整理成速查表，每一行都是真实踩过的场景：

4.3 部署阶段：Xshell推送前端构建产物与Nginx配置

部署是最容易在最后阶段翻车的地方。Vue项目构建后生成dist目录，我习惯用Xshell连接服务器后，通过rz命令上传压缩包，解压到指定目录。当然也可以直接服务器上拉Git代码，在服务器执行npm run build，两种方式各有优劣，看服务器配置和网络环境。

Nginx配置要准备三块：静态资源root指向dist目录；前端刷新404问题通过try_files解决；反向代理指向后端两个框架的入口。说直白点，try_files $uri $uri/ /index.html;这行配置能确保用户在前端路由下刷新页面时不跳出404。

后端部分，ThinkPHP和Laravel都要将站点根目录指向各自框架的public目录，运行目录绑定错了页面会直接暴露源码目录结构。PHP版本推荐8.0以上，配合ThinkPHP 6.0.12 LTS和Laravel 9/10都没有问题。每次发布前端代码前，先备份当前dist目录，出问题能快速回滚，这个习惯帮我避免过至少三次线上故障。

4.4 双框架协作中的一些开发规范

最后分享几个协作层面的经验。双框架项目比单框架更需要约定，不然维护者会疯掉：

• 错误码体系全局统一，比如10000开头为参数错误、20000开头为业务错误、30000开头为系统错误，两个框架共用一份错误码表；
• 接口文档从设计阶段就用Apifox维护好，前端Mock和后端调试同时进行；
• 数据库表结构变更时，两个框架的迁移脚本都要更新，最好由同一个人统一维护；
• 日志关键字带模块前缀，比如[TP]和[LAR]，出问题时能一眼辨别请求落在哪个框架。

我在实际项目里最深刻的体会是，框架选型没有绝对的标准答案，关键在于是否清楚每个框架擅长什么。ThinkPHP让资料模块快速落地，Laravel把审核、队列和内容服务的复杂度接住，Vue在前端把多端体验统一起来，这套组合对教育资源分享类项目确实是一个高性价比方案。如果你也在折腾类似的学习分享平台，希望这篇文章能帮你把架构和实现路径一次性理顺。最后再补一句：开发阶段就把业务错误码和HTTP状态码的对应规则规范好，后期联调和排查的效率能提升非常多，这是我从这个项目里收获最大的一个习惯。