这次要写的是“大学生国学自主学习平台”这个项目技术栈用的是 Node.js Vue。整个项目从环境搭到最终部署前后花了两个多月做下来最大的感受就是这类内容型平台技术选型一定要围绕“内容展示”和“学习路径”去设计而不是先敲定框架再反过来想页面。项目本身不算复杂但涉及的点很杂——用户登录、课程视频、文章阅读、学习记录、搜索、后台管理可以说麻雀虽小五脏俱全。先交代一下背景。平台面向的是在校大学生核心目标是让国学学习这件事不被“古文太枯燥”劝退。所以除了传统的文章阅读我加了视频课程、诗词朗读音频、书法字帖展示这些多媒体形态。内容形态一多对前端渲染和后端接口的灵活性要求就上来了。我最终选了 Vue 2 Node.jsExpress的组合前端做单页应用后端按 RESTful 接口提供数据中间用 JWT 做身份验证。下面就把整个项目的设计思路、核心实现、环境坑位和部署经验完整拆开讲。1. 项目整体设计与技术选型的底层逻辑1.1 为什么是 Vue 而不是 React很多人在项目立项时会在 Vue 和 React 之间犹豫我的结论很直接如果你的团队本来就更熟悉 JavaScript 而不是 JSX 的那套函数式思维Vue 的上手曲线明显更平缓。这个项目的开发成员大多是刚接触前后端分离的同学Vue 的单文件组件SFC把模板、脚本、样式放在一个.vue文件里几个人分工时不容易互相踩踏代码 review 的理解成本也低。另一个原因是 Vue 的指令系统特别适合内容展示类页面。比如v-for渲染课程列表、v-if按用户登录状态切换页面元素、v-model做搜索框和表单绑定几乎不需要写一堆document.getElementById的操作逻辑。像国学文章列表这种数据量大、结构相似的页面用 Vue 的组件复用可以把重复代码降到极低。我在项目里把“文章卡片”和“视频课程卡片”抽成了公共组件传给不同的 props 就能复用实际编码效率比一开始预想的高很多。当然 React 也不是不能用但对于这种以内容展示为主、交互相对中规中矩的场景Vue 的模板语法更直观。而且生态里 Element UI 这类组件库对表单、分页、表格的封装非常成熟后台管理页面基本是组装组件开发速度确实快。1.2 为什么用 Node.js 写后端选择 Node.js 而不是 Java Spring Boot 或 Python Django最直接的原因是前端语言栈的统一。前后端都用 JavaScript意味着接口返回的数据结构可以在大脑里直接映射到前端的data变量不需要在 Java 的 POJO 和前端对象之间来回转换心智。尤其在做联调时后端返回的字段名可以直接沿用前端设计好的命名省掉很多沟通成本。其次Node.js 在处理高 I/O 并发上有天然优势。国学校园平台在期末考试周容易有集中访问很多学生同时查资料、看视频而 Node.js 的事件驱动非阻塞模型对这类读多写少的场景很友好。我用了 Express 框架它本身非常轻量中间件机制清晰适合快速搭建 API 服务。数据存储选的是 MySQL因为用户信息、学习记录这类数据要求事务一致性MySQL 比 MongoDB 更稳。还有就是 Node.js 的 npm 生态实在太强了。我整个项目里用到的jsonwebtokenJWT 签发、bcryptjs密码加密、multer文件上传、cors跨域全都是现成的库安装即用不需要自己造轮子。这一点对内容型项目的快速迭代很有价值。1.3 国学学习场景的特殊需求拆解这个项目不是普通的内容管理系统它有三个比较特殊的点需要单独设计。第一个是“内容多样性”。国学学习既有文章比如《论语》章节又有视频比如教授讲解的公开课还有音频诗词朗诵。这就要求数据库的表结构不能只设计一个“文章表”而是要有统一的“课程或内容”概念通过content_type字段区分。我设计了一张course表同时存文章内容、视频 URL、音频 URL前端根据类型渲染不同组件。第二个是“学习连续性”。一个学生今天读到《道德经》第五章明天应该能继续从第五章开始而不是从头翻。这就需要记录学习进度。针对文章我记录了阅读到的段落位置针对视频我记录了播放进度秒数。这些数据都存在study_record表里关联用户和内容 ID。第三个是“检索需求”。学生查“仁”这个字应该能把《论语》里所有提到“仁”的章节都搜出来同时也能匹配相关的视频课名称。这要求后端有一个搜索接口在数据库里对标题、内容、标签字段做模糊匹配。后来发现 MySQL 的LIKE %keyword%在数据量达到数万条时会明显变慢所以我给相关字段加了全文索引并在搜索逻辑里优先匹配标题再匹配内容这种简单的权重排序已经能满足实际需求。2. 前端核心功能实现与细节处理2.1 Vue 组件化拆分与页面结构前端页面大概分成五个模块首页、课程列表页、文章阅读页、视频播放页、个人中心。我没用 Vue CLI 默认生成的一坨代码而是按照功能把目录拆成了views页面级组件、components业务组件、router路由配置、api接口封装、utils工具函数。首页是整个项目最花心思的页面。它需要展示“每日一句”“推荐课程”“热门文章”三个板块。如果全部堆在Home.vue里代码会变得非常臃肿。我抽出了DailySentence.vue、CourseCardList.vue、ArticleCardList.vue三个子组件各自的created生命周期里请求对应的数据接口。这样职责单一调试时也很清晰。一个值得提示的细节是组件的props传递。CourseCardList接收一个courses数组我在父组件里统一处理加载状态和错误状态传给子组件的永远是格式化好的数据。子组件内部只需要关注渲染这能避免很多因为数据结构不一致引发的隐性 bug。2.2 路由设计与权限控制Vue Router 在这个项目里分为两层不登录也能访问的公告页和必须登录才能访问的学习页面。我用router.beforeEach做全局守卫核心逻辑是判断路由 meta 里的requiresAuth字段如果有并且当前本地没有 token就跳转到登录页。这里注意一个容易被忽略的点hash模式和history模式的选择。开发时我用了默认的 hash 模式因为它在刷新时不会出现 404但这会带上#号不美观。在部署阶段我切换到了history模式同时必须在 Nginx 里配置try_files把所有路由都指回index.html否则刷新一个非根路径就会白屏。这是 Vue 项目尤其容易踩的坑。路由的懒加载也不要跳过。国学平台的文章页和视频页都比较重视频播放器本身有大几十KB的依赖如果全部打包进app.js首屏加载会慢得让人崩溃。我用路由级的代码分割const ArticleDetail () import(/views/ArticleDetail.vue)这样只有真正进入文章页时才会加载对应的 JS chunk。实测首屏打包体积从 1.2MB 降到了约 400KB。2.3 视频播放与 m3u8 流处理课程视频是这个项目的重头戏。学校提供的部分课程视频是 m3u8 格式的流媒体文件不是普通的 mp4。m3u8 本质是一个播放列表文件里面记录了一堆 ts 分片文件的地址浏览器原生 video 标签是不支持的。我的方案是用video.js配合videojs-contrib-hls插件。这里有一个非常关键的版本兼容问题如果video.js是 7.x一般用videojs-contrib-hls没有问题但如果你装的是某些旧版本会出现 “Cannot read property addClass of undefined” 这种莫名其妙的报错处理方式是统一升级到video.js7.6.6以上或者改用hls.js配合原生 video。我后来图省事直接改成hls.js方案逻辑上更纯粹通过Hls.isSupported()判断浏览器兼容性然后hls.loadSource(m3u8Url)hls.attachMedia(video)。播放进度记录是我自己实现的。监听 video 元素的timeupdate事件每 3 秒向后端上报一次当前播放秒数。这样做的原因是避免频繁请求打满接口3 秒一次在中断恢复时又能保证进度误差在 3 秒以内。恢复播放时后端返回上次的current_time前端在loadedmetadata事件后直接赋值video.currentTime savedTime体验上基本是无缝衔接。2.4 状态管理与接口封装很多人对 Vuex 的理解就是“全局变量”这个项目我确实没有过度使用它。我只有两处用了 Vuex用户状态登录后的用户信息和全局加载动画状态。其他数据像课程列表、文章列表都是组件内部自己管理的 data因为它们是页面级的不需要跨组件共享。接口封装我建议一定要独立成一个api目录。例如api/user.js里导出一个login(data)方法内部执行request.post(/user/login, data)。这个request是基于 axios 的封装统一设置了baseURL和timeout并在请求拦截器里自动带上Authorization: Bearer token。这样做有个好处如果有一天接口地址变了你只需要改一处 baseURL如果登录失效也只需要在响应拦截器里统一跳转登录页不用每个调用处都写一遍判断。一个我在实际开发中踩过的坑axios 拦截器里判断 HTTP 401 后不要直接在拦截器里跳转window.location.href /login这会让当前页面的操作状态丢失。应该router.push({ path: /login, query: { redirect: currentPath } })这样登录后还能跳回原页面体验好很多。3. Node.js 后端架构与数据交互3.1 后端接口设计与 RESTful 规范后端我用 Express 搭建整体按照资源路由来设计接口。这里分享几个比较典型的接口功能方法路径说明用户注册POST/api/user/register接收用户名、密码密码用 bcrypt 加盐后存库用户登录POST/api/user/login校验密码后签发 JWT获取课程列表GET/api/course/list支持分页参数page、size获取文章详情GET/api/course/:id返回文章内容和基础信息提交学习进度POST/api/study/record接入学习进度到study_record表获取我的学习记录GET/api/study/my返回用户学过的课程和进度RESTful 的好处是接口语义清晰前端可以根据动作直接猜测出路径。这里要注意 URL 里的资源命名统一用复数/api/courses避免一会/course一会/courses联调时找不到接口。另外接口层我做了一层响应格式的封装。所有成功响应统一返回{ code: 200, data: ..., message: ok }失败返回{ code: 4xx/5xx, data: null, message: 错误描述 }。这个看似多此一举实际上对前端异常处理帮助巨大。前端 axios 拦截器里只需要判断response.data.code是否等于 200不相等就弹出message不用纠结不同接口返回结构不一致的问题。3.2 用户体系与学习记录表设计用户表结构不算复杂但有两处需要注意。一是密码一定要用bcryptjs哈希存储绝对不要明文存。注册时用bcrypt.hashSync(password, 10)生成 hash登录时bcrypt.compareSync(password, user.password_hash)校验。10 是 salt rounds越高越安全但越慢10 在测试环境大概 100ms生产环境也能接受。二是学习记录表要想清楚唯一性约束。我用的是user_id course_id content_type三个字段做唯一索引。这样同一用户对同一课程只能有一条记录后续提交进度时走“存在则更新不存在则插入”的逻辑用 MySQL 的INSERT ... ON DUPLICATE KEY UPDATE一条 SQL 就能搞定性能和代码简洁度都很好。学习进度字段需要存储三个值current_time视频播放到第几秒、total_duration总时长、section_id如果是分章节的文章记录章节 ID。这三个值保证了进度的精确性和断点续看的可行性。还有一个last_study_time时间戳个人中心展示学习路径时很有用可以按时间倒序显示最近学的内容。3.3 中间件与鉴权逻辑Express 中间件机制是后端架构的骨架。我的中间件做了三层。第一层是cors中间件。前后端分离的开发环境中前端跑在localhost:8080后端跑在localhost:3000端口不同就会产生跨域。这个问题底层很简单浏览器同源策略限制了 AJAX 请求服务端通过设置Access-Control-Allow-Origin响应头来放行。第一天联调时我没配这个前端控制台里全是 CORS 报错后来直接app.use(cors())解决。生产环境因为走后端反向代理同源了其实可以不用但我为了省事保留着。第二层是 JWT 鉴权中间件。我写了一个authMiddleware从请求头里取出Authorization校验 token 是否有效并解析出user_id挂载到req.user_id上。所有必须在登录状态下使用的接口比如提交学习记录、获取个人学习列表都会使用这个中间件。如果 token 过期中间件直接返回 401前端会自动跳登录页。第三层是错误处理中间件。Express 4 里捕获异步错误比较麻烦我用了一个asyncHandler包装器把异步路由函数包一层让抛出的 error 自动传给 next(error)最后统一在错误处理中间件里返回500 { message: 服务器开小差了 }。不使用这个模式的话任何一个未捕获的 Promise rejection 都可能让整个进程挂掉尤其是数据库查询出问题时。3.4 关键词搜索与内容标签搜索功能我做了两层。第一层是关键词直接匹配WHERE title LIKE %keyword% OR content LIKE %keyword%。这在数据量小时够用但在《论语》全文检索里几十万字的内容扫描会比较慢。我加了一个content_ts字段用 MySQL 的FULLTEXT索引来处理。虽然 MySQL 全文索引的中文分词效果不如 Elasticsearch但对于这种单表几万条记录的项目性能已经足够。第二层是标签体系。我在每篇内容录入时人工配置了几个标签比如“仁义”“礼”“智慧”“修身”。课程表里加了一个tags字段存储逗号分隔的标签字符串。搜索时如果关键词命中了标签也会返回对应内容。这种“ETL式”的简单处理在内容量不大时比上一套复杂的搜索引擎划算得多。4. 环境配置与高频踩坑实录4.1 Node.js 安装与环境变量配置环境配置是整个项目第一个显眼坑位。很多同学下载 Node.js 安装包后一路 NextNode 本身能跑但npm install或者node -v会报错“不是内部或外部命令”。这绝大多数原因是环境变量没配好。Windows 下安装包如果不勾选“Add to PATH”安装完必须手动到“系统属性 - 环境变量”里把 Node.js 的安装路径比如C:\Program Files\nodejs加到Path变量里。这里补充一个细节安装版 Node.js 会默认把全局安装路径指向C:\Users\用户名\AppData\Roaming\npm这也是需要加入 PATH 的。否则后面npm install -g vue/cli后输入vue --version又会提示找不到命令。很多人的问题其实是出现在这一步。配置完成后在 cmd 或 PowerShell 里跑npm config get registry默认应该是https://registry.npmjs.org/国内环境下载慢到崩溃时可以改成https://registry.npmmirror.com这个镜像源。这个操作我几乎每个新环境都会做要不然后面装 Vue 依赖能装到怀疑人生。4.2 解决 npm.ps1 禁止运行脚本的问题这是撞到概率极高的问题而且报错信息非常扎眼npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本。这其实是 PowerShell 的执行策略在作怪。Windows 默认的 PowerShell 执行策略是Restricted不允许运行任何.ps1脚本文件而 npm 本身是一个.ps1包装脚本。在 cmd 里跑npm -v正常但在 PowerShell 里就跑不了。解决方案有两条二选一。一条是打开管理员权限的 PowerShell运行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser然后输入Y确认。这个策略允许本地脚本运行只禁止未签名的远程脚本。另外一条更省事直接用 cmd 而不是 PowerShell。但 VSCode 的默认终端就是 PowerShell很多同学就是在这里卡住所以还是建议执行策略改掉。还有一个关联问题如果用的是 VSCode 的终端改了执行策略后需要重新加载窗口才能生效。有一次我以为没改成功折腾半天发现只是没重置终端。4.3 Vue 依赖安装与镜像加速npm install卡住或者报 ERESOLVE 错误几乎是每个前端项目的必修课。经典场景是安装 Vue 项目时vue-cli-service和node-sass这类旧依赖在 Node.js 18 以上版本下会编译失败。后来我把项目升级到 Vue CLI 5 或者直接使用 Vite就能规避大部分 node-sass 兼容性问题。依赖安装慢的问题最优解是设置镜像源但很多人忽略了一个更快的工具——pnpm。它通过硬链接共享依赖装包速度比 npm 快很多。不过我自己的项目还是用的 npm因为它最通用团队协作时别人不用额外学 pnpm。如果项目里出现了unsupported engine的警告我一般先看 Node 版本必要时用nvm切换版本而不是去强改依赖版本。在这里也提醒一句不要随便删除node_modules后在 Windows 上快速重装。大项目删除时如果有文件占用会出现删不干净的提示导致node_modules残留残缺文件再用npm install时行为怪异。我推荐用rimraf node_modules这个跨平台删除工具或者至少先关闭正在进行的 Node 进程。4.4 不同系统下的 Node.js 安装对比这个项目在不同系统上都部署过差异还是不小的。Windows 上最方便的是安装包或者用nvm-windows做多版本管理。需要注意安装包方式自带的 npm 可能不是最新建议装完先跑一次npm install -g npmlatest升级 npm 自身。Ubuntu 上如果直接用apt-get install nodejs大概率装到一个很老的版本比如某系统只提供 Node 12。而 Vue 3 或 Vite 要求 Node 16所以一定不要图省事用 apt 默认源。正确流程是去 NodeSource 添加仓库curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -然后sudo apt-get install -y nodejs。这条路径我重复过很多次每次都能在几分钟内装到指定版本。macOS 上一般用brew install node或者用n这个版本管理工具。核心原则是不要再纠结系统默认版本统一用版本管理工具能省掉后面 90% 的“为什么我这里跑不起来”问题。4.5 Electron 打包 Vue 项目时的注意事项热词里提到了 electron 打包 vue 项目还有主进程渲染进程 IPC 的问题。我把 Vue 打包成桌面应用时碰到过一个比较隐蔽的坑在浏览器里跑得好好的接口请求打包到 Electron 里全部 404。原因是 Electron 的渲染进程文件是通过file://协议加载的而 localStorage 和 cookie 的行为和浏览器不完全一样请求没有带 token 或跨域策略导致失败。解决方案是用 IPC 通信绕开浏览器的网络限制让渲染进程把请求参数发给主进程由主进程用 Node.js 的net模块发起 HTTP 请求再把结果通过 IPC 回传。或者更简单在webPreferences里配置nodeIntegration: false然后在渲染进程的preload脚本中通过contextBridge暴露自定义 API。这也对应了 Electron 主渲染进程 IPC 通信与 Vue 的关系本质上没有关联是两套独立机制。如果你只是想要一个“手机外壳版”的 Vue 应用可以考虑用 Uni-app 或 Capacitor 这类跨端框架而不是纯 Electron。Electron 打包出来的体积至少一百多 MB移动端肯定不实用。5. 部署上线与性能优化5.1 前后端分离部署方案我的生产部署方案是经典的三层结构Nginx 托管前端静态文件、Nginx 反代后端接口、后端用 pm2 守护进程。前端打包后生成dist/目录里面有index.html和一堆带 hash 的 JS/CSS 文件。把这整个目录上传到服务器然后 Nginx 的 root 指向它。后端代码单独放在服务器某个目录先npm install --production然后用pm2 start app.js --name guoxue-api启动。注意 pm2 的名字要单独起不然下次 deploy 时容易记不清哪个是哪个。部署过程中最关键的坑是history模式的刷新 404。前端如果用了 Vue Router 的 history 模式Nginx 配置里必须加location / { try_files $uri $uri/ /index.html; }没有这句进入/article/123页面后刷新Nginx 会去找服务器上不存在的文件路径直接 404。加上try_files后所有请求都会回到index.html由 Vue Router 接管。5.2 Nginx 反向代理与跨域处理后端接口域名是api.guoxue.example.com前端是www.guoxue.example.com如果直接用前端发请求到后端域名就会出现跨域。虽然前端配置里已经允许 CORS但更体面的做法是让 Nginx 反代把/api/开头的请求转发给本地的3000端口。Nginx 配置里我加了一段location /api/ { proxy_pass http://127.0.0.1:3000/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; }注意proxy_pass的 URL 末尾带了/含义是去掉请求路径中的/api前缀。比如请求/api/user/login实际转发给后端的是/user/login。这要求后端接口在设计时就不要带/api前缀而是在 Nginx 层统一加上。这样改起来最干净后端所有路由都只写业务路径。使用这套方案后前端 axios 的baseURL可以直接配/api生产和开发环境只需要改环境变量不需要再关心 CORS。前面后端加的cors中间件就可以在生产环境移除减少一层请求处理开销。5.3 内存优化与进程守护Node.js 应用是单进程跑在服务器上的进程挂了服务就没了。pm2 最大的价值就是守护进程它的解释很简单我丢给 pm2 一个启动命令pm2 会盯着这个进程如果发现它退出了会自动重新拉起来。用法是pm2 start app.js --name guoxue-api --max-memory-restart 512M--max-memory-restart 512M表示内存占用超过 512MB 就自动重启。这个数值需要观察实际运行情况不能拍脑袋设太低。我一个武术类内容项目静态资源少内存大概在 250MB 左右设置 512M 很安全。开发时还要注意 Node.js 的垃圾回收。如果接口有内存泄漏跑几天后内存会缓慢上升。排查方式用node --inspect开启调试再用 Chrome 的 memory 快照看堆内存。当然最有效的办法还是规范代码习惯大数组处理完就置空、数据库查询结果记得释放、避免在全局变量里累积数据。写在最后最后再分享一个我个人的小习惯。每次项目做完我都会写一份 README里面记录环境版本Node 版本、npm 版本、MySQL 版本和启动命令。原以为这是多此一举直到一个月后我重新打开这个项目发现完全忘了当初用的 Node 14 还是 Node 16而依赖在那个版本下才跑得通。版本锁定这件事真的别偷懒。这个项目还有一个可以扩展的方向就是把学习记录做成可视化成套数据比如学生在国学平台上的学习时长分布、热门内容排行。这些功能加在一起能让平台从“内容展示”升级为“学习行为分析”对后续的教学改进会很有价值。但那些都是后话了先把当前这套系统用稳定比什么都强。
