uni-app 系统学习，从入门到实战（二）—— 项目结构解析

全篇大概 2000 字（含代码），建议阅读时间 10min

一、UniApp 目录结构详解

UniApp 基于 Vue.js 开发，其目录结构遵循约定大于配置的原则，以下是一个标准项目的核心目录结构：

pages # 页面目录（核心）
index # 首页
index.vue # 页面组件
index.scss # 页面样式
static # 静态资源（图片、字体等）
components # 自定义组件
uni_modules # 插件市场安装的模块
common # 公共工具（JS、CSS）
App.vue # 应用入口组件
main.js # 应用入口脚本
pages.json # 全局页面配置（核心）
manifest.json # 应用发布配置（核心）
uni.scss # 全局样式变量

1.1 核心目录说明

pages 目录
- 每个子目录对应一个页面，必须包含 .vue 文件。
- 页面路径需在 pages.json 中注册后才能访问。
static 目录
- 存放静态资源（如图片、字体），通过绝对路径 /static/logo.png 引用。
- 打包时会直接复制到输出目录，不建议存放大型文件。
components 目录
- 存放全局复用组件，通过 @/components/xxx.vue 引入。

二、pages.json：页面路由与全局样式配置

pages.json 是 UniApp 的核心配置文件，负责管理页面路由、导航栏样式、底部 TabBar 等全局设置。

2.1 基本结构示例

bash 复制代码

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页",
        "enablePullDownRefresh": true
      }
    }
  ],
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarBackgroundColor": "#FFFFFF"
  },
  "tabBar": {
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "首页"
      }
    ]
  }
}

2.2 核心配置项解析

pages 数组

path: 页面路径（相对于项目根目录）

style: 页面独有样式配置（覆盖全局配置）

globalStyle

全局导航栏、背景色、下拉刷新等样式配置。

tabBar

底部导航栏配置，最多支持 5 个 Tab。

2.3 最佳实践

使用 condition 字段实现动态路由（如根据用户权限显示不同页面）。
通过 easycom 配置自动引入组件，避免手动注册。

三、manifest.json：应用发布与多端适配

manifest.json 是应用的发布配置文件，用于配置应用名称、图标、启动页、权限等平台相关设置。

3.1 基本结构示例

bash 复制代码

{
  "name": "MyApp",
  "appid": "__UNI__XXXXXX",
  "versionName": "1.0.0",
  "mp-weixin": {
    "appid": "wx1234567890",
    "permission": {
      "scope.userLocation": {
        "desc": "需要获取您的位置信息"
      }
    }
  },
  "h5": {
    "title": "My H5 App",
    "router": {
      "mode": "history"
    }
  }
}

3.2 多平台配置策略

公共配置 ：name, versionName, appid 等全局生效。
平台专属配置 ：如 mp-weixin（微信小程序）、h5、app（原生 App）等节点。

3.3 关键配置项

图标与启动页

bash 复制代码

"icons": {
  "android": "/static/logo.png",
  "ios": "/static/logo.png"
},
"splashscreen": {
  "alwaysShowBeforeRender": false
}

权限声明（微信小程序）

bash 复制代码

"mp-weixin": {
  "permission": {
    "scope.userLocation": {
      "desc": "获取位置用于导航功能"
    }
  }
}

复制代码

四、开发与发布流程优化

环境区分
- 通过 process.env.NODE_ENV 区分开发与生产环境。
- 在 manifest.json 中配置不同环境的 API 地址。
性能优化

使用 分包加载 减少首屏体积：

bash 复制代码

// pages.json
"subPackages": [
  {
    "root": "subpages",
    "pages": [ ... ]
  }
]

多平台发布
- 通过 HBuilderX 的 发行菜单 一键生成各平台代码包。
- 针对不同平台调整 manifest.json 中的配置（如微信小程序的 appid）。

五、常见问题与解决方案

页面白屏
- 检查 pages.json 中的路径是否正确。
- 确保页面组件包含 <template>, <script>, <style> 标签。
静态资源加载失败
- 使用绝对路径 /static/...，避免相对路径。
- 检查文件是否被正确复制到 dist 目录。
跨平台样式兼容
- 使用 uni.scss 定义全局样式变量。
- 通过条件编译实现平台差异化样式：

css 复制代码

/* #ifdef H5 */
.header { height: 44px; }
/* #endif */

总结

掌握 UniApp 的目录结构与核心配置文件（pages.json 和 manifest.json）是开发跨平台应用的关键。通过合理配置，可以实现：

高效路由管理
多平台差异化适配
一键打包发布