【Uni-App+SSM 宠物项目实战】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骆Downloadsmy-pet-custommypetsrcmainwebappfront（今日所有操作均在 front 目录下）。

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

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

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

点击顶部菜单栏 File → New → Project；在弹出的窗口中：
选择项目类型：Uni-App；输入项目名称：front（与后端 webapp 下的目录名一致，避免路径混乱）；选择模板：默认模板（包含基础目录结构，无需自定义）；选择保存路径：C:Users骆Downloadsmy-pet-custommypetsrcmainwebapp（确保项目创建后路径为 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骆Downloadsmy-pet-custommypetsrcmainwebappfrontmanifest.json

（2）编辑核心配置（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骆Downloadsmy-pet-custommypetsrcmainwebappfrontpages.json

（2）编写 TabBar 配置

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


{
  "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 配置“相机权限”，实现拍照上传功能。