Node.js + Vue 红色旅游网站开发实践：接口设计、视频播放与地图标记

做这个基于 Node.js + Vue 的红色旅游网站之前，我以为它无非是“景点介绍站”的换皮版本。真正把需求理完才发现，游客要的不只是列表和详情页，还有路线推荐、地图标记、宣传片播放、预约留资和心得体会提交这类交互功能。这篇文章把我从环境配置到上线部署的完整过程写下来，重点讲清楚接口设计、页面拆分、视频播放和地图标记这几个绕不开的硬骨头，也把我踩过的 npm 脚本权限、跨域、history 路由刷新 404 这些坑一并交代了。如果你正打算用 Node.js + Vue 做同类型的展示型网站，这篇可以直接拿去当参考。

1. 红色旅游网站的需求拆解：它不是普通的景点展示站

先说说项目背景。红色旅游网站的核心受众很明确：一类是个人游客，想查景点位置、开放时间、门票信息，看看宣传片决定要不要去；另一类是单位团体，要做党建或团建活动，需要提前了解路线、预约时间、对接讲解服务。两类人需求叠加之后，你会发现这个网站的信息架构其实比想象中复杂。

我在需求梳理阶段列出来的功能模块大致是这样：

• 首页：轮播大图、推荐景点、热门路线、最新资讯
• 景点列表：按区域筛选、关键词搜索、分页加载
• 景点详情：图文介绍、历史背景、地图定位、视频播放、开放时间、门票信息
• 路线推荐：多日游路线，路线里包含多个景点，展示顺序和停留时长
• 资讯动态：新闻列表和正文，后台可维护
• 用户中心：注册、登录、收藏景点、提交留言反馈
• 后台管理：景点、路线、资讯的增删改查

这类项目的“器材属性”很强：每个景点都有丰富的图文和视频素材，内容更新频繁，所以后台管理和富媒体展示是核心，而不是复杂业务逻辑。这一点决定了后端不需要过重的框架，前端反而要在组件复用和展示体验上下功夫。

做需求拆解时我特别提醒自己一件事：红色旅游的内容主体是革命旧址、纪念场馆、爱国主义教育基地，这类信息具有教育属性，网站页面必须保持庄重、清晰、加载快。图片压缩、视频采用流媒体播放、列表页首屏只加载摘要，这些都不是可选项，而是必须项。

2. 技术选型逻辑：为什么是 Node.js + Vue 而不是 Spring Boot + Vue

很多人在项目启动时都会纠结技术栈。尤其搜索词里大量出现 “springboot vue 前后端分离”，说明这套组合在相关领域很主流。但我最后选了 Node.js + Vue，原因很实际。

先说后端。这个项目的核心是内容查询和展示，属于典型的读多写少场景。Node.js 的异步非阻塞 I/O 在高并发读请求下表现很稳，单台云服务器撑一个内容型网站绰绰有余。更重要的是，前端已经用了 Vue，前后端统一用 JavaScript，团队成员不需要在两门语言之间来回切换，联调时的数据结构沟通成本也低。

Express 是我这次的首选框架，配 Sequelize 操作 MySQL。为什么不选 NestJS？NestJS 的依赖注入和模块化设计确实规范，但它带了一整套 TS 装饰器体系，对这个体量的项目来说偏重。Express 足够直白，中间件机制灵活，写起来不绕弯。

再看前端。Vue 3 的 Composition API 在组织页面逻辑时非常舒服，特别是景点详情页这种同时包含视频、地图、收藏、评论的复杂页面，逻辑可以按功能拆成多个 composable 函数，代码不会堆成一团。Vite 的开发服务器启动速度比 Webpack 快一个量级，改代码热更新几乎是秒级，这对频繁调试页面样式和接口联调太重要了。

我整理过一张选型对比表，给团队评审时用过，这里直接贴出来：

表格不是刻板的结论，而是根据项目特性来的：内容展示型网站最需要的是快速迭代、团队产出效率高、部署轻量，Node.js + Vue 恰好踩中了这几个点。数据库我选了 MySQL，因为景点、路线、资讯之间的关系非常结构化，用关系型数据库做筛选、分页、关联查询都比文档型数据库顺畅。

3. 环境搭建与第一个拦路虎：npm 脚本执行权限问题

项目启动前，团队里有新人第一次配 Node.js 环境，结果卡在了最常见的“npm : 无法加载文件 ...npm.ps1，因为在此系统上禁止运行脚本”这个报错上。如果你用的 Windows 系统，八成也见过这个提示。

这个问题的原因很简单：Windows 默认的 PowerShell 执行策略是 Restricted，禁止执行本地脚本文件。npm 本身是一个 .ps1 脚本，PowerShell 出于安全策略拒绝运行它，但 Node.js 本身已经装好了。解决办法不是卸载重装，而是调整当前用户的执行策略。打开 PowerShell，执行：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

输入 Y 确认之后，再用命令验证一下策略是否生效：

Get-ExecutionPolicy

看到输出 RemoteSigned 就说明没问题了。RemoteSigned 的含义是：本机创建的脚本可以运行，从网上下载的脚本必须有数字签名才能运行。这是兼顾安全和开发便利的最常用策略，不需要把执行策略改成 Unrestricted。

Node.js 本身的安装倒是简单，去官网下载 LTS 版本安装包，一路下一步即可。安装完成后检查版本，确认环境变量配置是否生效：

node -v npm -v

如果 node 命令能显示版本号，但 npm 报错，多半就是上面说的执行策略问题；如果 node 命令本身都找不到，那要去系统环境变量 Path 里确认 Node.js 安装目录是否已经写入。

这里插一个实际经验：国内开发者装完 Node.js 之后，建议第一时间把 npm 镜像切换到国内源，否则后面npm install装依赖会慢到怀疑人生：

npm config set registry https://registry.npmmirror.com

设置完成后用npm config get registry验证一下，输出镜像地址就说明配好了。这一步虽然不是必须的，但对开发体验的改善是立竿见影的。

接下来创建前端工程。我用的 Vite 官方脚手架：

npm create vite@latest red-tourism-web -- --template vue cd red-tourism-web npm install npm install vue-router@4 pinia axios npm run dev

依赖装好后，再用浏览器打开 Vite 提示的本地地址，看到默认页面就跑通了。开发期建议把 Vue DevTools 插件装上，调试组件状态和 Vue Router 跳转参数会直观很多。这个插件在浏览器扩展商店里直接搜 Vue DevTools 就能装，Vite 项目默认会开启 devtools 支持，不用额外配置。

4. 后端接口设计与数据模型：先把表结构想明白

很多内容型项目后期改得痛苦，问题不是代码写不好，而是表结构一开始就漏了字段。我做景点详情页时反复加字段，就是因为前期没把“视频 URL 要不要单独存”“开放时间是字符串还是时间区间”这类问题定死。

这次我用 MySQL 建库，字符集统一用 utf8mb4，因为这个字符集才能完整存下中文和 emoji 表情。下面是核心表的字段设计：

数据库在项目里只做了最基础的关联，没有搞复杂的外键约束，业务层的 Sequelize 模型去维护关系。这样开发期改表更灵活，上线后用后台管理系统维护数据也不容易被约束卡住。

后端我用的是 Express + Sequelize 这套结构，目录按功能模块拆：

server/ app.js # 应用入口，注册中间件和路由 config/ db.js # Sequelize 实例 models/ user.js scenic-spot.js route.js article.js favorite.js routes/ auth.js # 注册/登录 spots.js # 景点相关 routes.js # 路线相关 articles.js # 资讯相关 favorites.js # 收藏相关

拿景点模型举例，Sequelize 定义如下：

// models/scenic-spot.js const { DataTypes } = require('sequelize'); const sequelize = require('../config/db'); const ScenicSpot = sequelize.define('ScenicSpot', { id: { type: DataTypes.INTEGER, primaryKey: true, autoIncrement: true }, name: { type: DataTypes.STRING(100), allowNull: false }, region: { type: DataTypes.STRING(50) }, address: { type: DataTypes.STRING(200) }, longitude: { type: DataTypes.DECIMAL(10, 6) }, latitude: { type: DataTypes.DECIMAL(10, 6) }, cover: { type: DataTypes.STRING(255) }, videoUrl: { type: DataTypes.STRING(255) }, intro: { type: DataTypes.TEXT }, historyStory: { type: DataTypes.TEXT }, openTime: { type: DataTypes.STRING(100) }, ticketInfo: { type: DataTypes.STRING(200) }, status: { type: DataTypes.TINYINT, defaultValue: 1 } }, { tableName: 'scenic_spots', timestamps: true });

列表接口是内容网站最常用的接口，景点列表需要支持分页、区域筛选和关键词搜索。实现如下：

// routes/spots.js const express = require('express'); const { Op } = require('sequelize'); const ScenicSpot = require('../models/scenic-spot'); const router = express.Router(); router.get('/scenic-spots', async (req, res) => { const { page = 1, pageSize = 10, region = '', keyword = '' } = req.query; const where = { status: 1 }; if (region) where.region = region; if (keyword) where.name = { [Op.like]: `%${keyword}%` }; const { count, rows } = await ScenicSpot.findAndCountAll({ where, offset: (Number(page) - 1) * Number(pageSize), limit: Number(pageSize), order: [['createdAt', 'DESC']] }); res.json({ code: 0, data: { list: rows, total: count } }); }); module.exports = router;

登录注册这块我用的 JWT，流程很简单：注册时把密码用 bcrypt 加密存入数据库，登录时比对密码，验证通过后签发一个 token，前端把 token 存在 localStorage 里，之后每次请求通过请求头带过去。

关键接口清单给各位一个概括：

设计接口时我习惯把分页参数统一成page和pageSize，返回结构统一成{ code, data, message }。前后端联调时最怕的就是接口返回格式乱七八糟，统一约定之后，前端的 Axios 拦截器就只需要处理一个形状的数据。

5. Vue 前端页面拆分与路由设计：从首页到详情页的完整链路

前端这部分，我先说目录结构。Vue 项目最忌讳的就是所有页面逻辑堆在 views 里，组件复用度低。我的做法是：views 只放页面级组件，包含页面布局和数据请求；components 放可复用模块，比如景点卡片、路线卡片、轮播图、视频播放器；composables 放可复用逻辑，比如收藏操作、地图初始化。

src/ api/ # 接口请求封装 components/ SpotCard.vue VideoPlayer.vue MapView.vue composables/ useFavorite.js useMap.js router/ index.js stores/ # Pinia views/ Home.vue SpotList.vue SpotDetail.vue RouteDetail.vue ArticleList.vue Login.vue UserCenter.vue

Vue Router 的配置要点有两个。第一，详情页必须用带参数的动态路由，比如/spots/:id；第二，因为用了 HTML5 history 模式，刷新页面时不会丢参数，但上线时必须配合 Nginx 的try_files配置，否则刷新就 404，这个问题后面专门讲。

路由配置示例：

// router/index.js import { createRouter, createWebHistory } from 'vue-router'; const routes = [ { path: '/', name: 'home', component: () => import('../views/Home.vue') }, { path: '/spots', name: 'spot-list', component: () => import('../views/SpotList.vue') }, { path: '/spots/:id', name: 'spot-detail', component: () => import('../views/SpotDetail.vue') }, { path: '/routes/:id', name: 'route-detail', component: () => import('../views/RouteDetail.vue') }, { path: '/articles', name: 'articles', component: () => import('../views/ArticleList.vue') }, { path: '/login', name: 'login', component: () => import('../views/Login.vue') }, { path: '/user', name: 'user', component: () => import('../views/UserCenter.vue') } ]; const router = createRouter({ history: createWebHistory(), routes, scrollBehavior(to, from, savedPosition) { return savedPosition || { top: 0 }; } }); export default router;

在景点列表页跳详情页时，通过路由参数带 id，页面内部用route.params.id请求详情接口。这里有个小细节：同一个详情组件被复用的情况下，参数变化时组件不会重新触发 onMounted，需要用watch(() => route.params.id, ...)去重新请求数据。我第一次做的时候没注意，在列表页点“上一篇”“下一篇”切换景点时页面数据不更新，排查了半天才想起来是生命周期的问题。

Axios 请求封装也是前端的一个重点。所有请求统一走一个实例，请求拦截器自动加 token，响应拦截器统一处理 401 跳转登录和错误提示：

// api/request.js import axios from 'axios'; const service = axios.create({ baseURL: '/api', timeout: 10000 }); service.interceptors.request.use(config => { const token = localStorage.getItem('token'); if (token) config.headers.Authorization = `Bearer ${token}`; return config; }); service.interceptors.response.use( res => res.data, err => { if (err.response && err.response.status === 401) { window.location.href = '/login'; } return Promise.reject(err); } ); export default service;

首页的布局大概是这样的结构：轮播大图区域放精选景点的封面图，下面是一排景点卡片，再往下是路线推荐和资讯列表。这个页面是游客的第一印象，我对图片做了懒加载，首屏只渲染视口内的内容，接口在 Vue 组件挂载时请求，数据拿到后渲染，用骨架屏占位避免白屏。

景点详情页是所有页面里最复杂的：左侧是图片轮播和介绍，右侧是地图、开放时间、门票信息，页面底部是宣传视频播放器和收藏按钮。我把它拆成多个子组件，页面只负责组装和拉数据，子组件完全独立，这样后期加新功能不会互相污染。

6. 视频播放与地图标记：红色旅游网站的两个硬功能

做这类网站时，视频播放和地图展示是绕不过去的。搜索词里 “vue 播放 m3u8” 和 “vue 播放器” 出现频率很高，说明大家都被这个功能卡过。

先说 m3u8。红色旅游景区的宣传视频通常由外包制作公司提供，交付格式大概率是 HLS 流媒体，也就是.m3u8索引文件加一堆.ts切片文件。m3u8 本身不包含视频数据，它只是一个播放列表，浏览器拿到它之后按列表顺序拉取 ts 文件并连续播放。好处是支持码率自适应，网络差时自动切低清晰度，适合景区大视频的在线播放。

在 Vue 里播放 m3u8，我用的是 hls.js 封装组件。Safari 原生支持 HLS，其他浏览器需要 hls.js 把流重新转封装成浏览器可识别的格式。这个组件写一次，全站复用：

<!-- components/VideoPlayer.vue --> <template> <video ref="videoRef" controls playsinline></video> </template> <script setup> import { onMounted, ref, watch } from 'vue'; import Hls from 'hls.js'; const props = defineProps({ src: { type: String, required: true } }); const videoRef = ref(null); function playVideo(src) { const video = videoRef.value; if (Hls.isSupported()) { const hls = new Hls(); hls.loadSource(src); hls.attachMedia(video); } else if (video.canPlayType('application/vnd.apple.mpegurl')) { video.src = src; } } onMounted(() => playVideo(props.src)); watch(() => props.src, val => playVideo(val)); </script>

使用这个组件的页面只要传一个src属性就行。踩坑提醒：m3u8 的域如果和网站不在同一个域名，可能会导致跨域请求失败，视频无法加载。解决办法是让视频制作方把视频文件放到支持跨域头配置的 CDN 或对象存储上，存储端配置Access-Control-Allow-Origin后问题自然消失。排查这个问题时，打开浏览器开发者工具的 Network 面板看.m3u8和.ts请求的响应头，一抓一个准。

地图这个功能我给两种方案。如果嫌商业地图 SDK 的 key 申请和配额麻烦，可以用 Leaflet 配合 OpenStreetMap 的瓦片图，免费开发无限制，标注景点坐标、弹窗展示简介完全够用。如果是正式商用且需要路线规划、周边搜索这些能力，直接接腾讯地图或高德地图的 JavaScript API。

我的做法是写一个useMapcomposable 统一管理地图实例，景点详情页调用它初始化地图、放 marker、绑定点击弹窗：

// composables/useMap.js import { ref, onBeforeUnmount } from 'vue'; import L from 'leaflet'; export function useMap(containerRef) { const map = ref(null); function initMap(options = {}) { map.value = L.map(containerRef.value, options); L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', { attribution: 'OpenStreetMap' }).addTo(map.value); return map.value; } function addMarker(lat, lng, popupContent) { const marker = L.marker([lat, lng]).addTo(map.value); if (popupContent) { marker.bindPopup(`<div class="map-popup">${popupContent}</div>`); } return marker; } onBeforeUnmount(() => { if (map.value) { map.value.remove(); map.value = null; } }); return { map, initMap, addMarker }; }

路线推荐页还可以把多个景点的坐标连成一条线，用 Leaflet 的 Polyline 画出来，游客能直观看到整条路线的行程走向。这个功能做起来不难，但展示效果非常加分，我第一次给客户演示的时候他们专门提了这个功能。

7. 前后端联调、跨域处理与上线部署

开发期前后端在不同端口跑，最舒服的联调方式是 Vite 的反向代理配置。前端代码里 Axios 的 baseURL 直接写/api，开发服务器把所有/api开头的请求转发到后端的 3000 端口：

// vite.config.js import { defineConfig } from 'vite'; import vue from '@vitejs/plugin-vue'; export default defineConfig({ plugins: [vue()], server: { port: 5173, proxy: { '/api': { target: 'http://localhost:3000', changeOrigin: true } } } });

这样配置之后，前端代码里不需要写完整的后端地址，生产环境只需要让 Nginx 同样把/api转发给 Node 进程，前端代码一行都不用改。这是我最推荐的方式，比后端写 CORS 响应头省心得多，也不容易出安全问题。

开发后期，前端执行npm run build会生成 dist 目录，这是纯静态文件。后端 Node 项目用 PM2 守护进程跑起来，保证重启和开机自启：

pm2 start server/app.js --name red-tourism-server pm2 save pm2 startup

上线时我的 Nginx 核心配置长这样：

server { listen 80; server_name red-travel.example.com; root /var/www/red-tourism-web/dist; index index.html; location /api/ { proxy_pass http://127.0.0.1:3000/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } location / { try_files $uri $uri/ /index.html; } }

这里最关键的是try_files $uri $uri/ /index.html这一行。因为 Vue Router 用了 history 模式，直接访问/spots/3时服务器并没有这个物理文件，Nginx 找不到就会返回 404。加了这行之后，所有未匹配到真实文件的请求都会回退到 index.html，前端路由拿到地址自己解析出对应的页面。很多新手上线后刷新页面就白屏，90% 是这个配置漏了。

HTTPS 我用的是 certbot 自动申请和续期的免费证书，这里不多展开，但必须强调一点：上线前一定要把 HTTP 强制跳转到 HTTPS，否则接口返回的数据在传输中容易被篡改，尤其是登录接口的密码和 token。

8. 这个项目踩过的坑和最终的建议

最后把这次开发过程中真正浪费过我时间的问题汇总一遍，都是很容易复现的坑。

第一个是 MySQL 写入中文乱码。建库时忘了指定 utf8mb4，结果景点介绍里的中文全变成问号。解决办法是把库、表、字段的字符集全部改成 utf8mb4，而且要在建表时就确认，别等数据量大了再迁移。

第二个是 history 模式刷新 404。这个问题在开发时完全暴露不出来，因为 Vite 开发服务器自带 fallback，上线到 Nginx 才原形毕露。解决办法就是上面提到的try_files，属于一次性配置搞定的事，但排查时确实容易懵，因为更目录文件明明都在，就是刷新报错。

第三个是 m3u8 的跨域。这里多说一句：很多人以为前端配置了代理就万事大吉，但视频文件的域名是独立的，前端代理只在开发期有效，生产环境的视频请求是浏览器直接发起。到这一步只有两个选择，要么让视频源支持跨域，要么用 Nginx 对视频域名做反向代理转发，把跨域变成同域。

第四个是列表页和详情页的数据量控制。景点详情返回的全部字段可能上百 KB，列表页如果也用全字段，移动端流量直接爆掉。我的做法是列表接口用attributes限定只返回 id、名称、封面、区域这几个字段，详情接口才返回完整数据。

第五个是关于性能的。首页的轮播图我全部用 WebP 格式加懒加载，大图压缩到 200KB 以内；视频组件默认不加载，等用户滚动到视频区域才初始化 hls.js。整套优化做完之后，移动端首屏加载从原来的 3 秒降到 1.5 秒左右，体感差别非常大。

如果你也想复制这个项目，我的建议是：先花两天时间把表结构和接口文档定死，再写代码。内容型网站的前端页面再怎么调整，只要后端表结构稳定，改动成本都可控。反过来，表结构如果三天两头加字段，前端页面就得陪着一起改，项目就会陷入无休止的联调地狱。另外，这类网站最终数据是由运营人员维护的，后台管理的表单校验、富文本编辑、图片上传这些功能虽然不起眼，但实际影响使用体验的程度远超你想象，别把它放到最后才做。

做这个项目过程中我感触最深的一点是：红色旅游网站的技术难点并不是某个独立功能有多难，而是素材形态太多样——图片、视频、地图、图文混排的内容要在一个页面里协作展示。Node.js 负责稳定地输出数据，Vue 负责把这些素材组织成流畅的浏览体验，两者配合得当，这类项目做起来会非常顺手。希望这篇梳理能帮你少走几个弯路。