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 核心目录说明

1. pages 目录

   • 每个子目录对应一个页面，必须包含 .vue 文件。

   • 页面路径需在 pages.json 中注册后才能访问。

2. static 目录

   • 存放静态资源（如图片、字体），通过绝对路径 /static/logo.png 引用。

   • 打包时会直接复制到输出目录，不建议存放大型文件。

3. components 目录

   • 存放全局复用组件，通过 @/components/xxx.vue 引入。

---

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

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

2.1 基本结构示例

{"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 基本结构示例

{"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 关键配置项

• 图标与启动页

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

• 权限声明（微信小程序）

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

---

四、开发与发布流程优化

1. 环境区分

   • 通过 process.env.NODE_ENV 区分开发与生产环境。

   • 在 manifest.json 中配置不同环境的 API 地址。

2. 性能优化

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

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

1. 多平台发布

   • 通过 HBuilderX 的 发行菜单 一键生成各平台代码包。

   • 针对不同平台调整 manifest.json 中的配置（如微信小程序的 appid）。

---

五、常见问题与解决方案

1. 页面白屏

   • 检查 pages.json 中的路径是否正确。

   • 确保页面组件包含 <template>, <script>, <style> 标签。

2. 静态资源加载失败

   • 使用绝对路径 /static/...，避免相对路径。

   • 检查文件是否被正确复制到 dist 目录。

3. 跨平台样式兼容

   • 使用 uni.scss 定义全局样式变量。

   • 通过条件编译实现平台差异化样式：

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

---

总结

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

• 高效路由管理

• 多平台差异化适配

• 一键打包发布