全篇大概 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 基本结构示例
{"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": "获取位置用于导航功能"}} }
四、开发与发布流程优化
-
环境区分
-
通过
process.env.NODE_ENV区分开发与生产环境。 -
在
manifest.json中配置不同环境的 API 地址。
-
-
性能优化
使用分包加载减少首屏体积：
// pages.json
"subPackages": [{"root": "subpages","pages": [ ... ]}
]-
多平台发布
-
通过
HBuilderX的 发行菜单 一键生成各平台代码包。 -
针对不同平台调整
manifest.json中的配置（如微信小程序的appid）。
-
五、常见问题与解决方案
-
页面白屏
-
检查
pages.json中的路径是否正确。 -
确保页面组件包含
<template>,<script>,<style>标签。
-
-
静态资源加载失败
-
使用绝对路径
/static/...，避免相对路径。 -
检查文件是否被正确复制到
dist目录。
-
-
跨平台样式兼容
-
使用
uni.scss定义全局样式变量。 -
通过条件编译实现平台差异化样式：
-
/* #ifdef H5 */
.header { height: 44px; }
/* #endif */总结
掌握 UniApp 的目录结构与核心配置文件（pages.json 和 manifest.json）是开发跨平台应用的关键。通过合理配置，可以实现：
-
高效路由管理
-
多平台差异化适配
-
一键打包发布
