企业官网建设流程全解析

敲完最后一块代码、把前端页面在手机浏览器里缩放检查完，这个"Java基于SpringBoot+Vue的新农村风貌展示平台"算是正式交付了。做这类项目的起因很简单：镇里想把各村的自然风光、老建筑、特色农产品和旅游路线集中放到一个页面上，让外面的人搜得到、看得明白，也让村里自己有个能随时更新的宣传窗口。

这个项目从一开始就有清晰的技术轮廓——后端 Java SpringBoot 提供接口和文件存储，前端 Vue 做页面展示和后台管理，中间走 RESTful API 对接。整体不算重，但涉及到的点很全面，包括数据库设计、分页查询、文件上传、视频流播放、地图定位、跨域处理、Nginx 部署等。如果你正在学 SpringBoot 和 Vue 的整合开发，或者需要做一个信息展示类项目、课程设计、毕业设计，这篇文章应该能提供一套完整可参考的实践方案。

我会按一个真实项目的推进顺序来说，从需求拆解到技术选型，再到后端、前端、部署，每个环节都带上关键代码和实际踩坑记录。

1. 这个平台到底要做什么

1.1 项目背景与需求来源

"新农村风貌展示平台"这个名字听起来有点大，落到实际需求上其实非常具体。我接到这个需求的时候，对方先给我看了一堆现有的宣传材料：各个村庄自己做的公众号推文、短视频账号、宣传折页，内容都很丰富，但是特别分散。游客想来村里玩，想知道哪里有民宿、哪里能采摘、古建筑有哪些，往往要翻好几个公众号，信息还不一定最新。村里想更新一处新修的步道或农家乐，也要找公众号运营去排版发布，效率很低。

所以整理下来，核心诉求就是三句话：第一，有一个统一的对外展示窗口，把各村的自然风貌、人文历史、特色产业集中呈现；第二，后台要能自主维护，管理员可以自己上传图片、视频、文章，不需要每次找开发人员改页面；第三，要同时兼顾 PC 和手机端，因为基层居民和游客大部分是用手机访问的。

这个背景决定了项目的基本形态：一个信息展示为主、内容管理为辅的 Web 平台，不追求复杂的业务逻辑，但要求在展示效果、访问速度、内容维护便利性上做扎实。

1.2 功能清单与核心需求拆解

把需求翻译成功能模块，我大致分成前台展示和后台管理两块，前台对外，后台对内。

这里有一个很关键的取舍：前台不要做登录注册。展示平台的核心是"让信息被看到"，如果把内容藏到登录后面，反而违背了初衷。游客可以直接浏览所有公开内容，只有进入后台管理页面时才需要账号校验。这样既保证了体验，又降低了复杂度。

我当时的做法是，在前台放一个候选接口列表，首页、列表页、详情页都由这些接口支撑；后台管理单独走一套接口，用 JWT 做身份校验。文章等内容的阅读量也可以顺便统计，虽然这个数据不一定很精确，但对镇里来说，能看出哪些内容受欢迎，对后续运营有价值。

2. 技术选型与整体架构设计

2.1 为什么是 SpringBoot + Vue

这个项目选型基本没有太多纠结。一方面，Java SpringBoot 在中小型 Web 项目里非常成熟，一套 SpringBoot + MyBatis + MySQL 的组合，开发速度快、资料多、招人也好招，基层单位后续要维护或二次开发都容易找到人。另一方面，Vue 在前端组件化和工程化上的体验很好，生态里有 Element UI 这类现成后台组件库，做管理页面可以省下大量时间。

如果换成一个单体 JSP 项目当然也能做，但前后端不分离的话，页面维护和接口复用都会别扭。尤其这个项目有"前台展示 + 后台管理"两个界面，它们长得完全不一样，用一套模板硬混在一起开发体验很差。前后端分离的好处是，前端只关心页面渲染和交互，后端只提供数据接口，两个端可以并行开发，后续调整也互不影响。

还有一个小考虑是部署环境。对方服务器上没有复杂的集群条件，就是一个普通 Linux 云主机，所以我没有引入 Docker、Kubernetes 这些容器化方案，而是选择最简单可靠的方式：后端 jar 包用 systemd 守护，前端静态文件用 Nginx 托管。越简单的架构，在基层环境的长期运行中越稳定，排查问题也越容易。

2.2 系统架构与工程目录设计

整个系统的请求链路是：浏览器访问 Vue 打包后的静态页面，页面里的 ajax 请求走 /api 前缀，由 Nginx 反向代理到后端 SpringBoot 服务的 8080 端口，后端访问 MySQL 数据库并把数据以 JSON 格式返回。文件上传则直接写入服务器磁盘的一个 upload 目录，通过静态资源映射对外提供访问。

后端工程我用的是常规的包结构：

src/main/java/com/example/rural/ ├── config/ # 跨域、静态资源配置、MyBatis配置 ├── controller/ # 接口层 ├── entity/ # 实体类 ├── mapper/ # MyBatis映射接口与XML ├── service/ # 业务层 ├── common/ # 统一返回、异常处理、工具类 └── filter/ # 全局过滤器

前端工程用 Vue CLI 创建，目录上按页面维度组织：

src/ ├── api/ # 接口请求封装 ├── router/ # 路由配置 ├── views/ # 页面组件 ├── components/ # 复用组件 ├── utils/ # 工具函数 └── assets/ # 静态资源

这种结构说不上多惊艳，关键是清晰。后端按技术层次分包，前端按页面和功能分包，新接手的人能很快定位到代码。对于这种展示型项目，工程结构的重要性不亚于编码本身，因为后续很可能不是原开发者来做维护。

2.3 数据库模型设计要点

这个项目的表结构不复杂，核心就几张表：村落表 village、风貌内容表 scenery、文章表 article、视频表 video、用户表 admin_user、分类字典表 category。

我挑几个设计要点说一下。村落表里除了村名、简介、封面图外，我加了 sort 排序字段和 status 状态字段，status 为 0 表示隐藏、1 表示展示。这样管理员可以在后台先编辑内容、暂不发布，等准备齐全再一键上线；排序字段也很有用，比如镇里想重点推某个村，排在最前面就行，不需要改代码。

风貌内容表和视频表都通过 village_id 与村落表关联，这样设计是因为一个村会有多条风貌内容、多个视频，属于一对多关系。文章表单独拆出来，因为它不绑定某个村，可能是镇级动态或活动公告。经纬度字段我直接存在 village 表里，用 decimal(10, 6) 类型，别用 float，否则地图打点会偏得离谱。

MyBatis 的 mapper 里我用了 MyBatis-Plus 的 LambdaQueryWrapper 来写查询，简单查询不用拼 SQL，分页用它的分页插件，代码会干净很多。这个项目的数据量不大，单表甚至不用加索引都能跑得很顺，但我在 status、village_id 这种查询频率高的字段上还是加了普通索引，算是养成习惯。

3. SpringBoot 后端核心实现

3.1 实体建模与 MyBatis 分页

实体类我通常直接用 MyBatis-Plus 的注解风格，字段和数据库列对应关系写在注解里，这样就不用维护一大堆 XML 映射文件。

@Data @TableName("village") public class Village { @TableId(type = IdType.AUTO) private Long id; private String name; private String intro; private String coverUrl; private BigDecimal longitude; private BigDecimal latitude; private Integer sort; private Integer status; private LocalDateTime createTime; }

查询接口这里有个常见问题，就是列表页不能一次把全部数据丢给前端，数据多的时候页面会明显变慢。我在村落列表、文章列表这些接口上都做了分页。MyBatis-Plus 自带分页插件，配置一个拦截器就行，然后用 Page 对象接收参数：

@Service public class VillageServiceImpl extends ServiceImpl<VillageMapper, Village> { public IPage<Village> pageVisible(int pageNum, int pageSize) { Page<Village> page = new Page<>(pageNum, pageSize); LambdaQueryWrapper<Village> wrapper = new LambdaQueryWrapper<Village>() .eq(Village::getStatus, 1) .orderByDesc(Village::getSort) .orderByDesc(Village::getCreateTime); return this.page(page, wrapper); } }

前端分页参数我统一用 pageNum 和 pageSize，返回值里带上 total，前端就能根据总条数生成分页控件。这里要注意一个细节，如果第一页查出来 10 条，用户翻到第 5 页时因为内容下架导致数据不足(pageNum - 1) * pageSize大于 total，就要处理"防抖动"或直接回到第一页，否则用户会看到空白列表。我在前端做了判断：total 变化后如果当前页超出总页数，自动跳回第一页。

3.2 REST 接口设计与前后端联调

接口设计遵循一个简单的原则：按资源命名 URL，用 HTTP 方法表达操作。

前台接口和管理接口都挂在 /api 下，但管理接口加了 /admin 路径，方便通过拦截器做权限校验。所有接口的返回结构统一：

@Data public class Result<T> { private int code; private String msg; private T data; }

code 为 0 表示成功，非 0 表示业务异常。这个统一返回类很重要，前端 axios 拦截器可以统一处理 code，不需要每个接口写一遍判断。

前后端联调时最常遇到的是跨域问题。浏览器限制前端地址和后端地址不一致时的请求，解决思路有两个：开发环境用 Vue CLI 的 devServer 代理，把 /api 转发到后端；生产环境用 Nginx 反代到后端。我在后端也开启了一组跨域配置，主要为了方便调试和供一些外部工具调用。下面这段配置放在配置类里：

@Configuration public class CorsConfig implements WebMvcConfigurer { @Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping("/api/**") .allowedOriginPatterns("*") .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS"); } }

不过在正式项目里，allowedOriginPatterns 不建议配成*，最好限定到实际的前端域名，否则等于把接口开放给任何来源的网页调用。我在部署前把这里的配置收敛成了指定域名。

3.3 文件上传、静态资源映射与视频流支持

内容展示平台最核心的资源就是图片和视频。上传这块我用 SpringBoot 自带的 MultipartFile 就能搞定，关键在应用配置和磁盘路径的组织上。

spring: servlet: multipart: max-file-size: 200MB max-request-size: 500MB

max-file-size 决定了单个文件能传多大。200MB 对普通乡村宣传视频足够，对高码率长视频会偏紧，可以根据实际情况调。需要注意的是，如果前端一次上传多个文件，max-request-size 要留出余地，否则一次传 5 个 50MB 的图片都会报错。

上传代码这里不复杂，核心是生成唯一文件名并保存：

public String upload(MultipartFile file) { String original = file.getOriginalFilename(); String ext = original.substring(original.lastIndexOf(".")); String fileName = UUID.randomUUID().toString().replace("-", "") + ext; File target = new File(uploadDir + "/" + fileName); file.transferTo(target); return "/upload/" + fileName; }

为什么要用 UUID 重命名？因为不同用户上传的照片很可能重名，直接覆盖会导致图片错乱；而且用随机名可以避免文件名暴露信息，省去很多命名坑。不过这里不建议把 uploadDir 写死，我放在配置文件里，生产环境指到数据盘路径，避免系统盘被大量图片视频占满。

图片和视频上传后要能被浏览器访问，需要在 WebMvcConfigurer 里配置静态资源映射：

@Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("/upload/**") .addResourceLocations("file:" + uploadDir + "/"); }

配置完成后，上传的素材就能通过http://域名/upload/xxx.jpg直接访问了。

视频播放这块，我最初直接存 mp4 并用 HTML 的 video 标签播放，实测发现体验一般：文件大、网络稍慢就会一直卡缓冲，也没有进度记忆。后来把正式宣传视频统一用 FFmpeg 转成了 HLS 流，也就是 m3u8 加 ts 切片的形式。HLS 的好处是边下边播，天然适合长视频和弱网环境，前端用 hls.js 就能播放。切片文件同样存在 upload 目录下，通过静态映射访问，不需要额外部署流媒体服务器，这个方案在中小型项目里非常实用。

3.4 全局过滤器与接口安全细节

内容展示平台虽然不涉及支付、敏感数据，但作为公共服务项目，基本的接口防护还是要做。我做了三件事：XSS 过滤、参数校验、统一异常处理。

XSS 过滤针对的是内容管理功能。管理员上传的图文内容会进入富文本编辑器，如果没有过滤，攻击者可以在内容里嵌入一段恶意 script，游客访问时脚本就会在浏览器里执行。我用了一个全局过滤器，把请求体中的<script>、<iframe>、onerror=等危险关键字统一转义处理，这里要注意，富文本内容本身合法的 HTML 标签要保留，不能一刀切把尖括号全转掉，否则正文排版会乱。我的做法是维护一个黑名单，只对危险标签和事件属性做转移处理。

参数校验用 Spring 的 validation 注解，在 Controller 入参上加 @NotBlank、@Size 之类：

@PostMapping("/api/admin/village/save") public Result<?> save(@Validated @RequestBody VillageReq req) { ... }

这样能挡住很多空指针和脏数据。我的体会是，参数校验不只是为了"正规"，更是为了减少联调时两边沟通成本。前端漏传一个字段，后端报错信息明确说"村名不能为空"，比看一串堆栈有用得多。

统一异常处理用 @RestControllerAdvice，把业务异常和系统异常分别处理，业务异常返回友好提示，系统异常记录日志并返回固定文案，避免把异常堆栈直接暴露给用户。安全这块还有一个容易被忽略的点：管理端接口的 JWT 令牌过期后要返回 401，前端要捕获这个状态自动跳转到登录页，这个我在 Vue 的 axios 拦截器里写好了。

4. Vue 前端实现与交互细节

4.1 工程初始化、路由与请求封装

前端我用 Vue 2 的生态做的，准确说是 Vue CLI 4 + Vue Router 3，配合 Element UI 组件库。为什么没用 Vue 3？我接手时团队现有项目都在 Vue 2 上，组件库、插件都比较成熟，直接上手没有学习成本。如果你从零开始，用 Vue 3 + Vite + Element Plus 会更符合趋势，但下面的组件化思路是一样的。

先初始化工程并安装依赖：

npm install -g @vue/cli vue create rural-front cd rural-front npm install vue-router@3 element-ui axios

这里有个最常见的坑：npm 安装依赖时网络慢或者版本冲突。建议第一次装完依赖后，把 node_modules 目录和 package-lock.json 缓存好，后续换机器可以直接复现环境。我自己在配环境时卡过两次，一次是 Node 版本太高导致 node-sass 编译失败，换成 sass 的 JS 版本实现就解决了；另一次是 Vue Router 装成了 4.x，和 Vue 2 不兼容，路由一启动就白屏。排查这种问题，先看控制台报错，不用急着搜方案。

路由配置我按页面结构定义：

const routes = [ { path: '/', name: 'Home', component: () => import('@/views/Home.vue') }, { path: '/village/:id', name: 'VillageDetail', component: () => import('@/views/VillageDetail.vue') }, { path: '/article/:id', name: 'ArticleDetail', component: () => import('@/views/ArticleDetail.vue') }, { path: '/admin/login', name: 'AdminLogin', component: () => import('@/views/admin/Login.vue') }, { path: '/admin', component: () => import('@/views/admin/Layout.vue'), children: [ { path: 'village', component: () => import('@/views/admin/VillageManage.vue') }, { path: 'article', component: () => import('@/views/admin/ArticleManage.vue') } ], meta: { requiresAuth: true } } ]

详情页选用/village/:id这种动态路由，而不是把 id 塞进 query 参数，因为这样 URL 更语义化，分享链接也更干净。组件里用this.$route.params.id读取参数并请求详情接口。

请求封装我统一放在src/api/request.js，创建 axios 实例并设置拦截器。拦截器做两件事：请求头自动带上 token，响应里统一判断 code，非零弹提示，401 跳登录页。

request.interceptors.response.use( res => { if (res.data.code === 0) return res.data.data Message.error(res.data.msg) return Promise.reject(res.data) }, err => { if (err.response && err.response.status === 401) { router.push('/admin/login') } return Promise.reject(err) } )

4.2 首页风貌展示的组件拆分

展示平台的首页决定了第一印象，我花了比较多精力在这里。整体布局是：顶部导航 + 大屏轮播图 + 村落卡片列表 + 最新动态 + 页脚。

轮播图用 Element UI 的 el-carousel 组件，图片数据从后台的 banner 接口取，管理员可以随时换图。这里有个优化点，图片宽度我限制在 1920 以内，前端再用缩略图参数控制尺寸，避免第一次加载首页要下载好几个 10MB 的图，移动端用户根本受不了。

村落卡片列表我拆成一个VillageCard.vue组件，接收一个 village 对象，内部渲染封面图、村名、一句话简介和入口按钮。这样列表页和首页都能复用它，不算复杂的组件，但减少了重复代码。列表排序按照后端返回的 sort 字段来，后台可以控制展示顺序。

这里我想强调一下"组件化"的分寸。展示型项目不需要把每个 div 都拆成组件，拆得太碎反而让模板变得难读。我的标准是：一个组件在页面中至少被复用两次，或者它的内容独立性足够强，比如轮播图、卡片、评论列表这类，才值得单独拆出来。像首页这种一次性页面，直接在页面模板里写反而更好维护。

4.3 风貌视频播放与地图定位

视频展示是风貌平台的一个亮点功能。我用 hls.js 封装了一个视频组件，支持 m3u8 视频流，也兼容 mp4 直链：

import Hls from 'hls.js' export default { props: { src: String }, mounted() { if (this.src.includes('.m3u8') && Hls.isSupported()) { const hls = new Hls() hls.loadSource(this.src) hls.attachMedia(this.$refs.video) } else { this.$refs.video.src = this.src } } }

hls.js 的本质是让不支持 HLS 的浏览器也能播 m3u8 流。桌面端 Chrome、Firefox 原生不支持 .m3u8，移动端 Safari 反而原生支持，所以代码里要做能力判断。视频组件里我还加了封面图展示、播放按钮的加载状态，避免点击后黑屏几秒让人以为坏了。

地图定位我用的是腾讯地图 JavaScript API。在村落详情页放置一张地图，把经纬度渲染成标注，点击标注弹出村名。地图 api key 需要去腾讯位置服务官网申请，申请过程不复杂，就是实名认证后建一个应用拿到 key。这里有个经验：开发阶段可以把 key 的域名白名单放开到 localhost，上线后一定要改回线上域名，否则密钥泄露以后别人可以盗用你的配额。

定位在地图上后，我还加了一个"一键导航"的跳转链接，直接调用地图的 URL API 拉起导航。对游客来说，知道村在哪里和能不能开车过去是两回事，这个功能虽然实现起来只要一行代码，但基层反馈的使用率很高。

4.4 管理后台与发布流程

后台管理是整个平台的"生产工具"，设计原则是让非技术人员也能顺利操作。我用 Element UI 做了一套简单的后台布局，左侧菜单、右侧内容区，菜单项包括村落管理、内容管理、文章管理、上传记录。

村落管理页面用 el-table 展示列表，行内直接提供编辑、上下架、置顶、删除操作。编辑页面用 el-form 表单，字段对齐数据库设计，封面图用 el-upload 上传。这里要注意 el-upload 的 action 要指向后端的上传接口，并且带上 token 请求头。上传成功后拿到图片 URL，回填到表单的隐藏字段里，最后保存时随表单一起提交。

文章管理用富文本编辑器。我在选择上用了比较常规的方案，富文本编辑器不直接存 HTML 里的图片，而是通过一个自定义上传接口，让编辑器里的图片先传到我们的服务器。这样文章发布后图片不会依赖第三方，也不会失效。内容保存前，前端会把危险标签过滤一遍，后端还有一层 XSS 过滤器兜底，双保险。

整个发布流程走下来是：管理员登录后台，创建或编辑一个村落的展示资料，上传封面、相册、视频，填写简介和详情，点保存后在前台立即可见。如果内容还没准备好，就把状态设为隐藏，等全部齐全再上架。这种"内容可控"的后台，才是展示平台真正能长期运转的关键。

5. 部署上线与实测踩坑记录

5.1 打包部署与环境变量配置

部署前先把两个端分别打包：前端执行npm run build，生成 dist 静态目录；后端用 Maven 打包，mvn clean package -DskipTests生成 jar 包。

前端 dist 目录我整体传到服务器的 /usr/share/nginx/html 下，Nginx 配置了单页应用的路由回退，保证刷新详情页不出现 404：

server { listen 80; server_name rural.example.com; root /usr/share/nginx/html; index index.html; location / { try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://127.0.0.1:8080/api/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } location /upload/ { alias /data/rural/upload/; expires 7d; } }

后端 jar 包我用 systemd 守护进程托管，写一个简单的 service 文件，设置启动命令和环境变量。服务器上要先装 JDK，并配置 JAVA_HOME 环境变量，这一步是很多新手卡住的地方。装完 JDK 后命令行执行java -version能正常输出版本，就说明环境没问题。

上传目录放在 /data/rural/upload，独立于系统盘。这里有个教训，我第一次部署直接把上传路径放到了 /root/upload，结果磁盘满的时候把系统目录塞爆了，机器直接卡住。后来赶紧迁到独立数据盘目录，并在配置里把路径改成通过环境变量注入，避免打包时写死。

5.2 常见问题速查表

这一路下来我整理了一张常见问题表，都是实际遇到过并且确认过解决办法的。

5.3 一些真实的落地体会

项目做下来，我最深的感受是：这种"看起来简单"的展示型项目，真正花时间的往往不在技术难点，而在细节和运维习惯。基层单位不会每天给你提新需求，但只要平台上线了，图片打不开、视频卡顿、后台传不了文件这类问题，会比预想中出现得更频繁。稳定的静态资源访问路径、统一的上传目录、清楚的日志输出，这些底子打好了，后面会省心很多。

还有一个容易被忽视的点是移动端适配。前台大部分用户是用手机访问的，我在首页和详情页做了响应式布局，图片用懒加载，视频播放器使用移动端友好的控件。甚至我把封面图数量控制在一个范围内，因为移动端用户不会像桌面端那样滑动一堆图，精选五张以内、张张清晰，比堆二十张模糊的照片效果好得多。

在调试前端时，Vue DevTools 插件是必须装的，它能在浏览器里直接查看组件数据和路由状态，排查问题效率翻倍。有一次视频一直播不出来，我就是在 DevTools 里看到视频源 URL 拼接错误，几分钟就定位了，比盲猜快太多。

如果你准备照着这个思路做一个类似的平台，我建议先把"内容从哪来、谁去维护、展示给谁看"这三个问题想清楚。技术选型、代码结构都可以照抄参考，但内容运营的定位决定了信息架构。信息架构顺了，后面的开发就是执行层面的事情。

最后再分享一个小技巧：后台的"一键上架/下架"和排序功能，虽然实现成本不高，但实际使用频率非常高。我在几个类似项目里都发现，内容维护者最怕的不是操作复杂，而是功能不可控——发错了不能下架、想置顶又要找开发。所以做展示平台时，把内容状态管理和排序做灵活一些，用户会真心觉得这个系统好用。这大概也是这类项目交付后，能被对方持续用起来而不是闲置的最重要原因。