【Uni-App+SSM+MP 宠物实战】Day4：Uni-App 项目初始化

一、前言

前面三天我们完成了后端 SSM+MyBatis-Plus 框架搭建和 Druid 连接池配置，今天正式切换到前端开发 ------Uni-App 项目初始化。

Uni-App 是基于 Vue.js 的跨端开发框架，核心优势是 "一套代码多端运行"，能同时适配 H5、微信小程序、App 等平台，完美契合我们 "宠物服务平台" 多端触达用户的需求（比如用户可能用小程序快速预约服务，也可能用 H5 查看宠物日志）。

今天我们会从 "创建 Uni-App 项目" 开始，配置核心文件 manifest.json 和底部 TabBar，最后实现 H5 与小程序的跨端预览，为后续开发宠物列表、商家服务等页面打基础。

二、今日教学目标

掌握 HBuilder X 创建 Uni-App 项目的步骤，理解项目目录结构（如 pages、manifest.json 的作用）；

学会配置 manifest.json（小程序 AppID、H5 运行端口），解决 "跨端配置不兼容" 问题；

实现底部 TabBar（首页 / 宠物 / 商家 / 我的），并完成 H5 与小程序的跨端预览验证。

三、前置准备

已完成 Day1 环境搭建：HBuilder X（App 开发版）、微信开发者工具已安装，且微信开发者工具已开启 "服务端口"（设置 → 安全设置 → 勾选 "服务端口"）；

了解基础 Vue 语法：如组件化、vue 文件结构（template/script/style），Uni-App 语法与 Vue 高度一致，无需额外学习新语法；

项目关键路径参考：C:\Users\骆\Downloads\my-pet-custom\mypet\src\main\webapp\front（今日所有操作均在 front 目录下）。

四、代码实现（核心步骤）

1. 第一步：创建 Uni-App 项目（指定 front 目录）

打开 HBuilder X，按以下步骤创建项目，确保项目目录与后端 webapp 下的 front 目录一致：

点击顶部菜单栏 File → New → Project；

在弹出的窗口中：

- 选择项目类型：Uni-App；

- 输入项目名称：front（与后端 webapp 下的目录名一致，避免路径混乱）；

- 选择模板：默认模板（包含基础目录结构，无需自定义）；

- 选择保存路径：C:\Users\骆\Downloads\my-pet-custom\mypet\src\main\webapp（确保项目创建后路径为 webapp/front）；

点击 Create，等待项目创建完成，创建后 front 目录下会生成核心文件：

- pages：存放所有页面（如首页 index、宠物页 pet）；

- manifest.json：多端配置文件（小程序 AppID、H5 端口等）；

- pages.json：页面路由与 TabBar 配置文件。

2. 第二步：配置 manifest.json（多端核心配置）

manifest.json 是 Uni-App 多端适配的核心文件，需配置小程序 AppID 和 H5 运行端口，确保与后端端口兼容：

（1）打开 manifest.json 文件

路径：C:\Users\骆\Downloads\my-pet-custom\mypet\src\main\webapp\front\manifest.json

（2）编辑核心配置（JSON 格式）

替换默认内容为以下代码，关键配置已加注释：

json 复制代码

{
  "name": "mypet-宠物服务平台",  // 项目名称（显示在小程序/APP 标题栏）
  "appid": "__UNI__A075441",  // 微信小程序 AppID（需从微信公众平台申请，测试可先用测试 AppID）
  "description": "提供宠物医疗预约、用品购买、社区分享的跨端平台",
  "versionName": "1.0.0",  // 版本号
  "versionCode": "100",
  "uniStatistics": {
    "enable": false  // 关闭统计（可选）
  },
  // H5 端配置（关键：端口与后端一致，避免跨域问题）
  "h5": {
    "devServer": {
      "port": 8080,  // 与后端 Tomcat 端口一致（后端默认 8080）
      "proxy": {
        // 后续前端调用后端接口时，用 /api 代理后端地址（提前配置，避免跨域）
        "/api": {
          "target": "http://localhost:8080/mypet",  // 后端项目地址
          "changeOrigin": true,
          "pathRewrite": {
            "^/api": ""  // 路径重写：/api/xxx → http://localhost:8080/mypet/xxx
          }
        }
      }
    },
    "title": "宠物服务平台-H5版",  // H5 页面标题
    "router": {
      "mode": "hash"  // H5 路由模式（默认 hash，避免部署后路径问题）
    }
  },
  // 微信小程序配置（可选：设置导航栏颜色，贴合宠物主题）
  "mp-weixin": {
    "navigationBarBackgroundColor": "#4CAF50",  // 导航栏背景色（绿色，贴合宠物健康主题）
    "navigationBarTitleText": "宠物服务平台",
    "navigationBarTextStyle": "white",  // 导航栏文字颜色
    "usingComponents": true  // 启用自定义组件（后续会用到）
  }
}

关键提醒：

小程序 AppID 申请路径：登录微信公众平台 → 注册 "小程序" 账号 → 开发 → 开发设置 → 复制 "AppID"；

若暂时没有正式 AppID，可使用微信开发者工具的 "测试号 AppID"（创建项目时选择 "测试号"），但部分功能（如支付）会受限。

3. 第三步：配置 pages.json，实现底部 TabBar

底部 TabBar 是用户切换核心页面的入口，需在 pages.json 中定义页面路径和 TabBar 样式，步骤如下：

（1）打开 pages.json 文件

路径：C:\Users\骆\Downloads\my-pet-custom\mypet\src\main\webapp\front\pages.json

（2）编写 TabBar 配置

替换默认内容为以下代码，包含 "首页 / 宠物 / 商家 / 我的" 四个 Tab，代码已加注释：

json 复制代码

{
  "pages": [
    // 页面路径配置：每新增一个页面，需在这里注册（路径从 pages 目录开始）
    {
      "path": "pages/index/index",  // 首页路径
      "style": {
        "navigationBarTitleText": "首页"  // 首页导航栏标题
      }
    },
    {
      "path": "pages/pet/index",  // 宠物页面路径（后续开发宠物列表）
      "style": {
        "navigationBarTitleText": "宠物"
      }
    },
    {
      "path": "pages/shangjia/index",  // 商家页面路径（后续开发商家列表）
      "style": {
        "navigationBarTitleText": "商家"
      }
    },
    {
      "path": "pages/mine/index",  // 我的页面路径（后续开发个人中心）
      "style": {
        "navigationBarTitleText": "我的"
      }
    }
  ],
  // 底部 TabBar 核心配置
  "tabBar": {
    "color": "#666666",  // 未选中 Tab 文字颜色
    "selectedColor": "#4CAF50",  // 选中 Tab 文字颜色（与导航栏色一致）
    "backgroundColor": "#ffffff",  // TabBar 背景色（白色，简洁）
    "borderStyle": "black",  // TabBar 上边框颜色（黑色细边）
    "list": [
      // 第一个 Tab：首页
      {
        "pagePath": "pages/index/index",  // 对应 pages 中的首页路径
        "text": "首页",
        // 可选：添加 Tab 图标（建议用 40×40px 的 PNG 图，未选中/选中区分）
        "iconPath": "static/icons/home-unselected.png",  // 未选中图标路径
        "selectedIconPath": "static/icons/home-selected.png"  // 选中图标路径
      },
      // 第二个 Tab：宠物
      {
        "pagePath": "pages/pet/index",
        "text": "宠物",
        "iconPath": "static/icons/pet-unselected.png",
        "selectedIconPath": "static/icons/pet-selected.png"
      },
      // 第三个 Tab：商家
      {
        "pagePath": "pages/shangjia/index",
        "text": "商家",
        "iconPath": "static/icons/store-unselected.png",
        "selectedIconPath": "static/icons/store-selected.png"
      },
      // 第四个 Tab：我的
      {
        "pagePath": "pages/mine/index",
        "text": "我的",
        "iconPath": "static/icons/mine-unselected.png",
        "selectedIconPath": "static/icons/mine-selected.png"
      }
    ]
  },
  "globalStyle": {
    // 全局样式：所有页面默认生效
    "navigationBarBackgroundColor": "#4CAF50",  // 全局导航栏背景色
    "navigationBarTextStyle": "white",  // 全局导航栏文字颜色
    "backgroundColor": "#f5f5f5"  // 页面背景色（浅灰，避免刺眼）
  }
}

图标配置说明：

若暂时没有图标，可先删除 iconPath 和 selectedIconPath 配置，TabBar 会只显示文字；

图标下载推荐：Iconfont 搜索 "首页""宠物""商店" 等关键词，下载 "40×40px" 的 PNG 图，放在 front/static/icons 目录下（需手动创建 icons 文件夹）。

4. 第四步：跨端预览配置（H5 + 小程序）

Uni-App 支持一键预览到多端，需分别配置 H5 和小程序的预览步骤：

（1）H5 端预览

在 HBuilder X 左侧 "项目管理器" 中，选中 front 项目；

点击顶部菜单栏 运行 → 运行到浏览器 → 选择任意浏览器（如 Chrome） ；

等待编译完成，浏览器会自动打开 H5 页面，地址通常为 http://localhost:8080/（与 manifest.json 中 H5 端口一致）。

（2）小程序端预览

确保微信开发者工具已启动，且已登录微信账号；

在 HBuilder X 中，点击顶部菜单栏 运行 → 运行到小程序模拟器 → 微信开发者工具；

HBuilder X 会自动编译项目，并将项目导入微信开发者工具；

等待微信开发者工具加载完成，即可看到小程序预览界面。

五、效果验证

1. H5 端验证点

浏览器页面顶部显示 "宠物服务平台 - H5 版"（导航栏标题正确）；

页面底部显示 "首页 / 宠物 / 商家 / 我的" 四个 Tab，点击任意 Tab 能正常切换页面（无空白或报错）；

页面背景色为浅灰色（符合 globalStyle 配置）。

2. 小程序端验证点

微信开发者工具顶部导航栏为绿色，文字为 "宠物服务平台"（配置生效）；

底部 TabBar 文字未选中时为灰色，选中时为绿色（tabBar 颜色配置正确）；

切换 Tab 时无闪退、无控制台报错（控制台可通过 "调试器" 查看）。

六、常见问题与解决方案

问题描述	可能原因	解决方案
运行到微信开发者工具时，提示 "服务端口未开启"	微信开发者工具未开启 "服务端口"，HBuilder X 无法连接	1. 打开微信开发者工具 → 点击右上角 "设置" 图标 → 选择 "安全设置"；2. 勾选 "服务端口"，关闭微信开发者工具后重新尝试预览
小程序预览时提示 "AppID 无效"	manifest.json 中的 appid 不是从微信公众平台申请的有效 ID	1. 登录微信公众平台，复制 "开发设置" 中的正式 AppID；2. 替换 manifest.json 中的 appid，重新编译预览；3. 测试阶段可使用 "测试号 AppID"：微信开发者工具 → 新建项目 → 选择 "测试号"，复制测试 AppID
H5 预览时页面空白，控制台报 "404 Not Found"	pages.json 中未注册页面，或页面路径写错	1. 检查 pages.json 的 pages 数组，确保 "首页 / 宠物 / 商家 / 我的" 页面路径正确（如 pages/index/index）；2. 确认 pages 目录下存在对应的 index.vue 文件（如 pages/index/index.vue）
切换 Tab 时，小程序报 "pages/pet/index.json 未找到"	宠物页面的 index.json 文件缺失（Uni-App 每个页面需有对应的 json 文件）	1. 打开 pages/pet/index 目录；2. 新建 index.json 文件，写入默认内容：{"navigationBarTitleText": "宠物"}；3. 其他页面（商家 / 我的）同理补充 json 文件

七、工具类 / 框架特性拓展

Uni-App 核心配置文件 manifest.json 的作用

manifest.json 是 Uni-App 的 "多端配置入口"，除了今天配置的小程序和 H5，还能适配 App（Android/iOS）、支付宝小程序等，核心功能包括：

权限配置：如 App 端需要的 "相机权限"（后续宠物头像上传会用到）、"定位权限"（商家位置定位）；

性能优化：如 H5 端的 devServer.proxy（解决跨域）、小程序端的 usingComponents（启用自定义组件）；

品牌定制：如各端的导航栏颜色、启动页图片（后续可添加宠物主题的启动页）。

后续开发 "宠物日志发布页" 时，我们会通过 manifest.json 配置 "相机权限"，实现拍照上传功能。

八、结尾

今天我们完成了 Uni-App 项目的初始化和 TabBar 配置 ------ 你的跨端预览是否正常？比如小程序端的 Tab 图标是否显示正确，H5 端切换 Tab 时有没有空白页？

如果遇到 "图标错位""小程序连接失败" 等问题，欢迎在评论区分享你的 pages.json 或 manifest.json 关键代码（注意打码 AppID），我们一起排查；如果成功实现跨端预览，也可以晒出你的 H5 或小程序截图，让大家一起参考！

小马绿泡泡：Niuma4G

下期预告

Day5：数据库设计（梳理宠物服务平台核心表结构，如用户表、宠物表、商家表、服务预约表，编写 SQL 脚本初始化数据库，为后续前后端数据交互做准备）。