企业官网建设流程全解析

这次我们来看一套 2026 年新版的 uniapp + Vue3 全套实战教程。它不只是讲单个页面怎么做，而是把前台用户端和后台管理系统串在一起，从项目初始化、接口联调到打包上架，把一条完整的企业级项目链路走通。对于准备用 uniapp 做跨端应用、同时需要一个 Vue3 后台来管理数据和权限的开发者来说，这套内容比零散看文档要高效得多。

项目的核心看点有三个：第一，前台基于 uniapp + Vue3 组合式 API 开发，一套代码可以跑小程序、H5 和 App；第二，后台管理系统使用 Vue3 技术栈，包含登录、权限、菜单、数据管理等后台必备模块；第三，接口文档齐全，前后端联调时不需要靠猜字段，直接按文档对接即可。这套内容对刚入门的人友好，对已经在做 Vue2 项目、想切 Vue3 的开发者同样有参考价值。

本文会从环境准备开始，依次拆解前台商城项目的页面结构、后台管理系统的权限设计、接口文档的联调方式，最后补上打包上架和常见问题排查。文章里涉及的命令和代码都是通用示例，实际项目中请按自己的目录、请求地址和接口返回结构做调整。

1. uniapp + Vue3 核心能力速览

从学习路径看，建议按照“前台搭建 -> 接口联调 -> 后台管理 -> 打包发布”的顺序推进。先跑通前台的基础页面，再接入后台的登录和权限体系，最后把两端通过接口文档连接起来，形成一个完整闭环。

2. 适用场景与学习路径

这套教程最适合三类人。

第一类是刚接触 uniapp 的开发者。uniapp 的核心价值是“一套代码多端运行”，但多端运行也意味着要理解条件编译、平台差异、路由规范这些概念。如果直接从文档开始看，很容易被碎片化内容带偏。教程把前台页面、组件、路由、请求封装串起来，比单独看某个 API 更有效。

第二类是正在从 Vue2 迁移到 Vue3 的开发者。Vue3 的组合式 API 和 Vue2 选项式 API 写法差异很大，尤其是ref、reactive、computed、watch的使用方式，以及<script setup>语法。后台管理系统这部分能很好地展示 Vue3 在真实项目中的组织方式。

第三类是准备做前后端分离项目的全栈学习者。前台用 uniapp 做跨端应用，后台用 Vue3 做管理系统，接口文档充当两端的契约。这种项目结构非常接近真实公司里的开发模式，练完能直接迁移到工作项目中。

使用边界方面，需要明确几点：uniapp 虽然支持多端，但不同平台的 API 能力和 UI 表现存在差异，业务代码里要通过条件编译做适配；后台管理系统的权限设计只是前端控制，真正的安全控制必须依赖后端接口的权限校验；接口文档中的字段和地址是教程示例，接入真实后端时需要按实际接口调整。

3. 环境准备与项目初始化

3.1 开发工具准备

uniapp 开发可以选 HBuilderX 或 CLI 方式，两种方式各有特点。

HBuilderX 是 DCloud 官方 IDE，内置了 uniapp 的编译、运行、发布能力，对新手最友好。下载安装后，新建项目时直接选择“uniapp”模板，语言版本选择 Vue3，就可以开始开发。HBuilderX 还集成了小程序模拟器、App 真机运行、云打包等能力，不需要额外配置太多环境。

CLI 方式适合习惯命令行和团队协作的开发者。项目基于 Vue3 + Vite 初始化，依赖通过npm或pnpm管理，更适合与后端、测试等团队成员保持一致的工具链。

无论使用哪种方式，都建议先确认 Node.js 环境。CLI 方式下 Node 版本要满足 Vite 的要求，通常推荐使用 Node.js 18 及以上版本。HBuilderX 自带的运行环境可以减少一些版本兼容问题，但如果做复杂的自定义构建，CLI 更灵活。

3.2 新建前台项目

以 HBuilderX 为例，新建项目的操作是这样的。

打开 HBuilderX，选择“文件 -> 新建 -> 项目”，项目类型选择“uniapp”，模板选“默认模板”，框架选“Vue3”，点击创建即可。项目创建完成后，会生成以下核心目录：

├── pages/ # 页面目录 ├── static/ # 静态资源 ├── App.vue # 应用入口组件 ├── main.js # 入口文件 ├── manifest.json # 应用配置 ├── pages.json # 页面路由与配置 └── uni.scss # 全局样式变量

关键配置在manifest.json和pages.json两个文件。manifest.json管理应用名称、appid、小程序配置、App 打包配置等内容；pages.json管理页面路由、tabBar、导航栏样式和窗口表现。

{ "pages": [ { "path": "pages/index/index", "style": { "navigationBarTitleText": "首页" } }, { "path": "pages/category/category", "style": { "navigationBarTitleText": "分类" } } ], "tabBar": { "list": [ { "pagePath": "pages/index/index", "text": "首页" }, { "pagePath": "pages/category/category", "text": "分类" } ] } }

pages.json里注册的页面路径就是路由地址。uniapp 没有像 Vue Router 那样单独维护路由表，页面即路由，这一点和传统 Vue3 项目不同，需要先适应。

3.3 新建后台管理系统

后台管理系统建议直接用 Vue3 + Vite 初始化。如果不想从零搭建，可以使用现成的后台管理系统模板，模板一般已经集成了登录页、布局框架、动态路由、权限指令和 Axios 封装，能省去很多重复工作。

# 使用 Vite 创建 Vue3 项目 npm create vite@latest admin-web -- --template vue cd admin-web npm install npm run dev

创建完成后，目录结构大致如下：

├── src/ │ ├── api/ # 接口请求模块 │ ├── components/ # 公共组件 │ ├── layout/ # 后台布局 │ ├── router/ # 路由配置 │ ├── store/ # 状态管理 │ ├── views/ # 页面 │ ├── App.vue │ └── main.js ├── index.html ├── vite.config.js └── package.json

后台管理系统的核心不是页面数量，而是权限模型、路由守卫和状态管理。登录后拿到 token 和用户角色，前端根据角色动态生成可访问的路由，再通过路由守卫拦截未登录的访问。这个机制要和后端接口配合，确保页面权限和数据权限都受控。

4. uniapp 前台商城项目实战：从页面到接口

4.1 组合式 API 的基本用法

uniapp 从 Vue3 开始支持组合式 API，在<script setup>中写逻辑。和 Vue2 的data、methods、computed分块不同，Vue3 更强调按业务功能组织代码。

<script setup> import { ref, computed, onMounted } from 'vue' import { getHomeData } from '@/api/home.js' const bannerList = ref([]) const goodsList = ref([]) const loading = ref(false) const totalCount = computed(() => goodsList.value.length) const loadData = async () => { loading.value = true try { const res = await getHomeData() bannerList.value = res.data.bannerList goodsList.value = res.data.goodsList } finally { loading.value = false } } onMounted(() => { loadData() }) </script>

这是最常见的组合式 API 写法。ref用于定义响应式数据，computed用于派生状态，onMounted是生命周期钩子，对应 Vue2 的mounted。在 uniapp 项目里，除了 Vue 本身的生命周期，还会用到onLoad、onShow等页面生命周期。

4.2 uniapp 页面生命周期

uniapp 的页面生命周期由框架提供，写在<script setup>中直接引入使用。

<script setup> import { ref } from 'vue' import { onLoad, onShow, onPullDownRefresh, onReachBottom } from '@dcloudio/uni-app' const list = ref([]) const page = ref(1) onLoad((query) => { console.log('页面加载，参数：', query) loadList() }) onShow(() => { console.log('页面显示') }) onPullDownRefresh(() => { page.value = 1 loadList() uni.stopPullDownRefresh() }) onReachBottom(() => { page.value += 1 loadList() }) const loadList = async () => { const res = await getGoodsList({ page: page.value }) list.value = page.value === 1 ? res.data : [...list.value, ...res.data] } </script>

需要注意页面生命周期的执行顺序：onLoad只在页面首次加载时执行，onShow每次进入页面都会执行。列表页下拉刷新和触底加载是商城项目的常见需求，分页参数要正确维护，避免数据重复或遗漏。

4.3 请求封装与接口对接

前台项目的请求层需要统一封装，方便处理 token、错误提示和加载状态。uniapp 中通过uni.request发起请求，可以将其封装成一个 Promise 风格的函数。

// utils/request.js const BASE_URL = 'https://api.example.com' export const request = (options) => { return new Promise((resolve, reject) => { uni.request({ url: BASE_URL + options.url, method: options.method || 'GET', data: options.data || {}, header: { 'Content-Type': 'application/json', 'Authorization': uni.getStorageSync('token') || '' }, success: (res) => { if (res.statusCode === 200) { resolve(res.data) } else if (res.statusCode === 401) { uni.removeStorageSync('token') uni.navigateTo({ url: '/pages/login/index' }) reject(res) } else { uni.showToast({ title: res.data.msg || '请求失败', icon: 'none' }) reject(res) } }, fail: (err) => { uni.showToast({ title: '网络异常', icon: 'none' }) reject(err) } }) }) }

封装后的请求可以按业务模块创建 API 文件，比如首页、商品、订单、购物车等。

// api/home.js import { request } from '@/utils/request.js' export const getHomeData = () => { return request({ url: '/home/index', method: 'GET' }) } export const getGoodsList = (data) => { return request({ url: '/goods/list', method: 'POST', data }) }

真实项目中，接口地址应该通过环境变量管理，区分开发环境、测试环境和生产环境。别把接口地址硬编码在页面里，否则上线时改起来很痛苦。

4.4 商城核心页面拆解

一个典型的 uniapp 商城前台会包含这些页面：

• 首页：轮播图、金刚区入口、推荐商品列表
• 分类页：左侧分类导航 + 右侧商品列表
• 商品列表页：排序、筛选、分页
• 商品详情页：轮播、价格、规格选择、加购物车
• 购物车页：勾选、数量修改、结算
• 订单确认页：地址、商品清单、优惠
• 订单列表页：订单状态展示、取消、确认收货
• 个人中心页：用户信息、订单入口、设置

首页推荐用组件拆分，轮播图是一个组件，商品卡片是一个组件，商品列表是一个组件。组件化之后，其他页面也能复用商品卡片组件，避免重复代码。

<template> <view class="goods-card" @click="goDetail"> <image class="goods-image" :src="goods.image" mode="aspectFill" /> <view class="goods-info"> <text class="goods-name">{{ goods.name }}</text> <text class="goods-price">¥{{ goods.price }}</text> </view> </view> </template> <script setup> const props = defineProps({ goods: { type: Object, required: true } }) const goDetail = () => { uni.navigateTo({ url: `/pages/goods/detail?id=${props.goods.id}` }) } </script>

商品详情页的路径参数通过onLoad接收。这个页面通常需要请求详情接口、展示多图轮播、处理规格选择、加入购物车。规格选择是一个独立组件，维护一个selectedSpec对象，根据用户选择更新价格和库存。

5. Vue3 后台管理系统搭建：权限与菜单

5.1 登录与 token 管理

后台管理系统的基本流程是：用户输入账号密码，请求登录接口，后端返回 token 和用户信息，前端把 token 存起来，之后每次请求都在 header 里带上 token。

// store/user.js import { defineStore } from 'pinia' import { loginApi, getUserInfoApi } from '@/api/user.js' export const useUserStore = defineStore('user', { state: () => ({ token: localStorage.getItem('token') || '', userInfo: {} }), actions: { async login(loginForm) { const res = await loginApi(loginForm) this.token = res.data.token localStorage.setItem('token', res.data.token) return res }, async getUserInfo() { const res = await getUserInfoApi() this.userInfo = res.data return res.data }, logout() { this.token = '' this.userInfo = {} localStorage.removeItem('token') } } })

Pinia 是 Vue3 项目的主流状态管理方案，比 Vuex 更简洁。在后台管理系统中，用户信息、权限列表、菜单列表都可以放在 store 中统一管理。

5.2 动态路由与菜单权限

后台管理系统的权限控制通常在登录后完成：根据用户角色请求菜单接口，得到可访问的路由列表，然后动态添加路由并生成侧边栏菜单。

// router/index.js import { createRouter, createWebHistory } from 'vue-router' import { useUserStore } from '@/store/user.js' const router = createRouter({ history: createWebHistory(), routes: [ { path: '/login', component: () => import('@/views/login/index.vue') }, { path: '/', component: () => import('@/layout/index.vue'), redirect: '/dashboard', children: [] } ] }) router.beforeEach((to, from, next) => { const userStore = useUserStore() if (to.path === '/login') { next() return } if (!userStore.token) { next('/login') return } next() }) export default router

动态添加路由的方式：

const addDynamicRoutes = (menus) => { const routeComponents = import.meta.glob('@/views/**/*.vue') const buildRoutes = (menuList) => { return menuList.map(menu => { const route = { path: menu.path, name: menu.name, meta: { title: menu.title, icon: menu.icon } } if (menu.component) { route.component = routeComponents[`/src/views/${menu.component}.vue`] } if (menu.children && menu.children.length) { route.children = buildRoutes(menu.children) } return route }) } const dynamicRoutes = buildRoutes(menus) dynamicRoutes.forEach(route => { router.addRoute(route) }) }

菜单接口返回的数据结构要和路由定义保持一致。建议后端直接返回树形结构，前端根据这个结构动态生成菜单和路由。这里的关键是路由组件路径要和后端返回的component字段对齐，否则会出现页面空白。

5.3 后台页面示例：商品管理列表

后台管理系统最常见的页面是表格页，核心功能包括搜索、分页、新增、编辑、删除、状态切换。以商品管理为例：

<template> <div class="product-page"> <el-card> <el-form :inline="true" :model="queryForm"> <el-form-item label="商品名称"> <el-input v-model="queryForm.name" placeholder="请输入商品名称" clearable /> </el-form-item> <el-form-item label="状态"> <el-select v-model="queryForm.status" placeholder="请选择状态" clearable> <el-option label="上架" value="1" /> <el-option label="下架" value="0" /> </el-select> </el-form-item> <el-form-item> <el-button type="primary" @click="handleSearch">查询</el-button> <el-button @click="handleReset">重置</el-button> </el-form-item> </el-form> </el-card> <el-card> <el-button type="primary" @click="handleAdd">新增商品</el-button> <el-table :data="productList" v-loading="loading"> <el-table-column prop="id" label="ID" width="80" /> <el-table-column prop="name" label="商品名称" /> <el-table-column prop="price" label="价格" width="120" /> <el-table-column label="状态" width="100"> <template #default="{ row }"> <el-tag :type="row.status === 1 ? 'success' : 'info'"> {{ row.status === 1 ? '上架' : '下架' }} </el-tag> </template> </el-table-column> <el-table-column label="操作" width="180"> <template #default="{ row }"> <el-button link type="primary" @click="handleEdit(row)">编辑</el-button> <el-button link type="danger" @click="handleDelete(row)">删除</el-button> </template> </el-table-column> </el-table> <el-pagination v-model:current-page="queryForm.page" v-model:page-size="queryForm.pageSize" :total="total" :page-sizes="[10, 20, 50]" layout="total, sizes, prev, pager, next, jumper" @change="loadList" /> </el-card> </div> </template>

表格页的开发节奏通常是：先写搜索表单和表格列，再写接口请求，最后处理分页参数。Element Plus 的表格、表单、弹窗组件封装度比较高，适合快速开发后台。如果项目有 API 文档，字段名直接对着文档写，能减少很多沟通成本。

6. 接口文档设计与联调

6.1 接口文档的核心内容

接口文档是前后端协作的契约，一套完整的接口文档应该包含以下内容：

• 接口地址和请求方式
• 请求参数：参数名、类型、是否必填、说明
• 请求头：token、Content-Type
• 返回结果：code、message、data 结构
• 错误码说明
• 示例请求和示例响应

以商品列表接口为例，接口文档通常这样描述：

POST /api/goods/list 请求头： Authorization: Bearer <token> 请求参数： { "page": 1, "pageSize": 10, "name": "手机", "status": 1 } 返回结果： { "code": 200, "message": "success", "data": { "list": [ { "id": 1, "name": "手机", "price": 3999, "status": 1 } ], "total": 100 } }

统一的返回结构非常重要。如果后端每个接口的返回结构都不一样，前端就得在请求层做大量兼容处理。建议约定一个标准结构，比如{ code, message, data }，code为 200 表示成功，其他为业务错误。

6.2 Swagger 与接口文档管理

后台管理系统通常用 Swagger 或类似工具管理接口文档。Swagger 可以通过注解自动生成接口文档，减少手工维护的成本。

Swagger 带来的好处是接口信息实时同步，后端接口有变动，文档会跟着更新。前端可以直接在 Swagger 页面上查看参数定义和返回结构，甚至可以直接复制请求示例。

但需要注意，Swagger 文档描述的是后端接口的原始定义，前端对接时还需要在请求层做二次封装。不要把接口文档里的所有字段都直接暴露给页面组件，应该按业务模块在src/api目录下建立独立的接口函数。

6.3 前后端联调流程

一个标准的联调流程是这样的：

1. 后端提供 Swagger 或接口文档地址。
2. 前端根据文档创建 API 请求模块。
3. 本地开发时通过 Vite 或 HBuilderX 的代理配置，将接口请求转发到后端测试环境。
4. 联调过程中，如果发现字段缺失或返回结构不一致，及时和后端确认并更新文档。
5. 联调完成后，将接口地址切换到生产环境，再做一轮全量回归。

uniapp 前台和后台管理系统是两个独立项目，但接口文档是同一个。也就是说，前台商城和后台商品的增删改查操作的是同一套后端接口数据，只是入口不同。这正好解释了为什么这套教程要把前台和后台放在一起学：它能直观展示一套接口如何支撑两个前端应用。

7. 项目打包与上线

7.1 uniapp 打包为微信小程序

在 HBuilderX 中，选择“运行 -> 运行到小程序模拟器 -> 微信开发者工具”，即可将 uniapp 项目编译为微信小程序并自动打开微信开发者工具。

首次使用需要在小程序开发工具中配置 AppID。如果只是本地预览，可以使用测试号。如果需要真机预览或发布，需要注册小程序账号并获取正式 AppID。

发布步骤是：在微信开发者工具中点击“上传”，填写版本号和备注，然后到微信公众平台的版本管理页面提交审核，审核通过后发布上线。

7.2 uniapp 打包为 App

uniapp 打包 App 有两种方式：云打包和本地打包。

云打包不需要本地配置 Android SDK 和 iOS 环境，直接在 HBuilderX 中点击“发行 -> 原生App-云打包”，选择 Android 或 iOS 平台即可。云打包需要 DCloud 开发者账号，支持使用公共证书或自定义证书。

本地打包需要在 manifest.json 中配置 SDK 版本，然后下载对应平台的离线 SDK 进行集成。本地打包更适合需要对原生代码做定制的团队，比如接入特定的原生插件或推送 SDK。

App 打包完成后，Android 会生成 APK 或 AAB 文件，iOS 需要上架 App Store，审核流程在小程序平台之外。

7.3 后台管理系统部署

后台管理系统是 Vue3 项目，构建后得到的是静态文件，可以部署到 Nginx、Tomcat 或对象存储服务上。

# 构建生产环境代码 npm run build

构建产物在dist目录中。以 Nginx 为例，部署配置如下：

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

这里的关键配置是try_files $uri $uri/ /index.html，作用是让所有路由都指向index.html，由前端路由接管页面跳转。否则刷新一个二级路由页面会出现 404。

8. 资源占用与性能观察

8.1 uniapp 前台性能观察

uniapp 项目在开发阶段运行在模拟器中时，CPU 和内存占用取决于编译工具和模拟器的开销。HBuilderX 开发和微信开发者工具同时开启时，内存占用会比较高，建议开发机上保留 16GB 以上内存。

前台性能优化的重点不在开发工具，而在运行时表现。pages.json中注册的页面数量、首页请求数量、图片资源大小都会影响小程序的启动速度。关注这几个指标：

• 首页首屏请求数量：控制在 5 个以内
• 图片大小：使用压缩后的图片，建议单张不超过 200KB
• 页面切换耗时：通过onShow和onLoad打印日志查看

8.2 Vue3 后台性能观察

后台管理系统是浏览器端应用，性能观察主要看页面加载速度和接口响应时间。打开 Chrome DevTools 的 Network 面板，可以查看每个接口的耗时和资源加载情况。

后端管理系统的性能瓶颈通常在大列表页面。如果商品列表数据量过大，需要后端做分页和过滤，前端不要一次性加载所有数据。表格超过 100 行时，建议使用虚拟滚动。

实际占用数据需要在各自环境中测试：启动多个前端项目、后端服务和浏览器后，观察任务管理器中的 CPU 和内存占用，根据项目规模调整开发机配置。

9. 常见问题与排查方法

上面这些问题是开发过程中最高频的几类。uniapp 项目中，not found:page是新手最容易遇到的，原因是pages.json里的路径没有写对。后台管理系统中，刷新 404 是部署阶段最容易踩的坑，原因是 Nginx 没有做前端路由的 fallback 配置。

10. 最佳实践与建议

10.1 前台项目推荐做法

1. 页面目录按业务模块划分，不要把所有页面都堆在 pages 根目录下。
2. 请求层统一封装，不要在页面里直接调用uni.request。
3. 多端差异用条件编译处理，不要用大量 if 判断平台。
4. 公共组件抽出来，商品卡片、图片上传、规格选择都是高频组件。
5. 图片资源做压缩，必要时使用 CDN。
6. tabBar 页面使用uni.switchTab跳转，普通页面使用uni.navigateTo。

10.2 后台项目推荐做法

1. 权限控制用动态路由，菜单和路由由后端接口下发。
2. token 过期后统一跳转登录页，不要在页面里各自处理。
3. 大列表页面用分页和筛选，不要一次加载全量数据。
4. Pinia 中只放跨页面共享的状态，页面局部状态不要都塞进 store。
5. 接口请求函数按模块组织，一个页面一个 API 文件，方便维护。

10.3 接口联调建议

1. 接口文档里统一返回结构{ code, message, data }，不要混用。
2. 请求封装里集中处理 401、403、网络异常等通用错误。
3. 开发环境用代理解决跨域，不要在浏览器里禁用安全策略。
4. 字段命名保持统一，建议后端使用小驼峰。
5. 联调过程中发现问题，先确认是不是文档过期，再排查代码逻辑。

10.4 合规与安全提醒

• 后台管理系统涉及用户数据、订单数据等敏感信息时，必须在接口层面做权限校验。
• 前台商城涉及用户支付、地址、手机号等信息，需要明确隐私政策并告知用户。
• 不要在前端代码中硬编码后端密钥、数据库连接信息等敏感配置。
• 上架到各大应用市场和小程序平台时，需要提供符合平台要求的软件著作权证明、隐私协议等材料。
• 如果接入第三方地图、支付、推送服务，遵守对应平台的合规要求。

11. 总结与后续建议

这套 uniapp + Vue3 前后台教程最值得尝试的点，是把前台跨端应用和后台管理系统放进同一个项目框架里，配合完整接口文档，让学习者能真正理解一个企业级项目是怎么协作的。新开发者在完整实现前台页面和后台权限后，会对 uniapp 的多端运行逻辑和 Vue3 的组合式 API 形成系统认知，而不是只停留在看文档的阶段。

刚开始实践时，建议先从小程序端前台做起，把首页、商品列表、商品详情这条主链路跑通，然后搭建后台管理的登录和动态路由，最后再让两个项目对接同一套接口。先小范围验证，再逐步加功能。

过程中最容易踩的坑有两个：一是 uniapp 页面路由和pages.json配置不一致导致跳转失败，二是后台管理系统部署后刷新 404。这两个问题在本文的排查清单中已经有对应方案，建议收藏备用。

后续如果时间充裕，可以继续扩展这些方向：给前台加上登录功能、购物车逻辑和在线支付；给后台加上角色管理、操作日志和数据统计；将接口文档接入自动化测试；在 HBuilderX 中完成 App 云打包并上架应用市场。把这套链路完整走完，基本就掌握了 uniapp + Vue3 在企业项目中的主流开发模式。