uni-app 项目结构详解

本文将详细介绍 uni-app 项目的文件结构，帮助您更好地理解和组织项目代码。

概述

uni-app 项目结构遵循 Vue.js 规范，同时具有自己的特殊文件和目录。理解项目结构是开发 uni-app 应用的基础。

基本项目结构

my-uni-app/
├── uniCloud/                   # 云开发目录（可选）
│   ├── cloudfunctions/         # 云函数目录
│   └── database/               # 数据库目录
├── components/                 # 组件目录
│   └── comp-a.vue             # 可复用组件
├── pages/                      # 页面目录
│   ├── index/
│   │   └── index.vue          # 首页
│   └── list/
│       └── list.vue           # 列表页
├── static/                     # 静态资源目录
│   ├── images/                # 图片资源
│   └── fonts/                 # 字体资源
├── uni_modules/               # uni_module 插件目录
├── store/                     # 状态管理目录（可选）
├── api/                       # API 接口目录（可选）
├── utils/                     # 工具函数目录（可选）
├── main.js                    # Vue 初始化入口文件
├── App.vue                    # 应用配置文件
├── manifest.json              # 应用配置清单
├── pages.json                 # 页面路由配置
├── uni.scss                   # 全局样式变量（可选）
└── package.json               # 项目依赖配置

提示：uni-app 项目结构遵循 Vue 规范，同时也有自己的特殊文件。

核心文件详解

1. pages.json - 页面路由配置

pages.json 文件用来对 uni-app 进行全局配置，决定页面文件的路径、窗口样式、原生的导航栏、底部的原生 tabbar 等。

基本结构

json

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页"
      }
    },
    {
      "path": "pages/list/list",
      "style": {
        "navigationBarTitleText": "列表页"
      }
    }
  ],
  "globalStyle": {
    "navigationBarTextStyle": "white",
    "navigationBarTitleText": "uni-app",
    "navigationBarBackgroundColor": "#42b983",
    "backgroundColor": "#F8F8F8"
  },
  "tabBar": {
    "color": "#7A7E83",
    "selectedColor": "#42b983",
    "borderStyle": "black",
    "backgroundColor": "#ffffff",
    "list": [
      {
        "pagePath": "pages/index/index",
        "iconPath": "static/tab-home.png",
        "selectedIconPath": "static/tab-home-active.png",
        "text": "首页"
      },
      {
        "pagePath": "pages/list/list",
        "iconPath": "static/tab-list.png",
        "selectedIconPath": "static/tab-list-active.png",
        "text": "列表"
      }
    ]
  }
}

主要配置项

pages：页面路径配置
- path：页面路径
- style：页面窗口样式
globalStyle：全局样式配置
- navigationBarTextStyle：导航栏标题颜色（black/white）
- navigationBarTitleText：导航栏标题文字
- navigationBarBackgroundColor：导航栏背景颜色
- backgroundColor：窗口背景色
tabBar：底部 tab 栏配置
- color：tab 文字默认颜色
- selectedColor：tab 文字选中颜色
- backgroundColor：tab 背景色
- list：tab 列表（2-5个）

2. manifest.json - 应用配置清单

manifest.json 文件是应用的配置文件，用于指定应用的名称、图标、权限等。

基本结构

json

{
  "name": "uni-app示例",
  "appid": "__UNI__XXXXXXX",
  "description": "uni-app示例工程",
  "versionName": "1.0.0",
  "versionCode": "100",
  "transformPx": false,
  "app-plus": {
    "usingComponents": true,
    "nvueCompiler": "uni-app",
    "splashscreen": {
      "alwaysShowBeforeRender": true,
      "waiting": true,
      "autoclose": true,
      "delay": 0
    }
  },
  "mp-weixin": {
    "appid": "wx开头的微信小程序appid",
    "setting": {
      "urlCheck": false
    },
    "usingComponents": true
  },
  "h5": {
    "router": {
      "base": "/"
    },
    "optimization": {
      "treeShaking": {
        "enable": true
      }
    }
  }
}

主要配置项

基本信息
- name：应用名称
- appid：应用标识
- description：应用描述
- versionName：版本名称
- versionCode：版本号
平台配置
- app-plus：App 特有配置
- mp-weixin：微信小程序特有配置
- mp-alipay：支付宝小程序特有配置
- h5：H5 特有配置

3. App.vue - 应用入口组件

App.vue 是 uni-app 的主组件，所有页面都是在 App.vue 下进行切换的，是页面入口文件。

基本结构

vue

<script>
export default {
  onLaunch: function() {
    console.log('App Launch')
  },
  onShow: function() {
    console.log('App Show')
  },
  onHide: function() {
    console.log('App Hide')
  }
}
</script>

<style>
/* 全局样式 */
.container {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
}
</style>

应用生命周期

onLaunch：当 uni-app 初始化完成时触发（全局只触发一次）
onShow：当 uni-app 启动，或从后台进入前台显示
onHide：当 uni-app 从前台进入后台

4. main.js - Vue 初始化入口

main.js 是 uni-app 的入口文件，主要作用是初始化 Vue 实例、定义全局组件、使用需要的插件等。

基本结构

javascript

import Vue from 'vue'
import App from './App'

// 引入全局组件
import myComponent from './components/my-component.vue'
Vue.component('my-component', myComponent)

// 引入全局样式
import './common/uni.css'

// 引入状态管理
import store from './store'

// 引入全局方法
Vue.prototype.$api = {
  formatDate(date) {
    return date.toLocaleDateString()
  }
}

Vue.config.productionTip = false

App.mpType = 'app'

const app = new Vue({
  store,
  ...App
})
app.$mount()

主要功能

Vue 实例化和挂载
全局组件注册
全局样式引入
状态管理配置（Vuex）
全局方法和过滤器添加

目录结构详解

pages 目录

pages 目录存放所有业务页面文件，是应用的核心目录。

特点

每个页面应有一个单独的目录
目录名称与页面名称相同
每个页面目录下必须有一个同名的 vue 文件
页面可以嵌套，支持多级目录结构

目录结构示例

pages/
├── index/
│   └── index.vue          # 首页
├── list/
│   └── list.vue           # 列表页
└── user/
    ├── user.vue           # 用户主页
    └── profile/
        └── profile.vue    # 用户资料页

components 目录

components 目录存放可复用的组件，提高代码复用性。

特点

组件可以在多个页面中使用
组件可以嵌套使用
支持 easycom 规范自动注册
建议按功能或业务模块分类

目录结构示例

components/
├── common/                # 通用组件
│   ├── navbar.vue
│   └── tabbar.vue
├── form/                  # 表单组件
│   ├── input.vue
│   └── button.vue
└── business/              # 业务组件
    └── product-card.vue

static 目录

static 目录存放应用引用的本地静态资源。

资源类型

图片、视频、音频等媒体文件
字体文件
第三方的 js、css 等资源
其他静态文件

目录结构示例

static/
├── images/
│   ├── logo.png
│   └── icons/
│       ├── home.png
│       └── user.png
├── fonts/
│   └── iconfont.ttf
└── js/
    └── third-party.js

uni_modules 目录

uni_modules 目录存放符合 uni_module 规范的插件。

特点

每个插件是一个单独的目录
插件可以包含组件、JS SDK、页面模板、项目示例等
插件可以方便地导入导出和共享
支持插件市场一键安装

目录结构示例

uni_modules/
├── uni-calendar/
│   ├── components/
│   │   └── uni-calendar/
│   │       └── uni-calendar.vue
│   ├── pages/
│   │   └── calendar/
│   │       └── calendar.vue
│   └── package.json
└── uni-popup/
    ├── components/
    │   └── uni-popup/
    │       └── uni-popup.vue
    └── package.json

uniCloud 目录

uniCloud 目录存放云开发相关文件（仅云开发项目）。

主要子目录

cloudfunctions：云函数目录
database：数据库目录，存放数据库 Schema 和扩展校验函数

目录结构示例

uniCloud-aliyun/
├── cloudfunctions/
│   ├── common/
│   │   └── index.js
│   ├── getUser/
│   │   └── index.js
│   └── updateUser/
│       └── index.js
└── database/
    ├── db_init.json
    └── user.schema.json

特殊文件说明

文件名	说明
`uni.scss`	全局样式变量文件，可在此定义全局通用的样式变量
`vue.config.js`	Vue CLI 的配置文件，可对 webpack 进行自定义配置
`package.json`	项目配置文件，记录项目依赖和脚本命令
`tsconfig.json`	TypeScript 配置文件（仅 TypeScript 项目）
`README.md`	项目说明文档

项目结构最佳实践

1. 目录命名规范

使用小写字母和连字符（kebab-case）
目录名应简洁明了，如 user-profile
避免使用中文或特殊字符

2. 组件分类管理

按功能分类：表单组件、导航组件、布局组件等
按业务分类：商品组件、订单组件、用户组件等
使用清晰的目录结构便于维护

3. 静态资源管理

在 static 目录下按类型分类存放
图片资源按功能模块分组
合理压缩图片大小，提升加载性能

4. API 统一管理

创建 api 目录统一管理接口
按业务模块封装 API 请求函数
统一处理请求和响应拦截

5. 状态管理

使用 Vuex 管理全局状态
创建 store 目录，按模块组织代码
合理划分 state、mutations、actions

完整项目结构示例

my-uni-app/
├── uniCloud-aliyun/            # 云开发目录（阿里云）
├── components/                 # 组件目录
│   ├── common/                # 通用组件
│   │   ├── navbar.vue
│   │   └── tabbar.vue
│   └── business/              # 业务组件
│       └── product-card.vue
├── pages/                     # 页面目录
│   ├── index/
│   │   └── index.vue         # 首页
│   ├── category/
│   │   └── category.vue      # 分类页
│   ├── cart/
│   │   └── cart.vue          # 购物车页
│   └── user/
│       └── user.vue          # 用户页
├── static/                    # 静态资源目录
│   ├── images/               # 图片资源
│   │   ├── logo.png
│   │   └── icons/
│   │       ├── home.png
│   │       └── user.png
│   └── fonts/                # 字体资源
│       └── iconfont.ttf
├── store/                     # Vuex 状态管理
│   ├── index.js              # 入口文件
│   └── modules/              # 状态模块
│       ├── user.js
│       └── cart.js
├── api/                       # API 请求封装
│   ├── index.js              # API 入口
│   ├── request.js            # 请求封装
│   └── modules/              # API 模块
│       ├── user.js
│       └── product.js
├── utils/                     # 工具函数
│   ├── format.js             # 格式化工具
│   └── validate.js           # 验证工具
├── config/                    # 配置文件
│   ├── index.js              # 主配置
│   └── env.js                # 环境配置
├── uni_modules/               # uni_module 规范插件
├── main.js                    # 入口文件
├── App.vue                    # 应用配置
├── manifest.json              # 打包配置
├── pages.json                 # 页面配置
├── uni.scss                   # 全局样式变量
└── package.json               # 项目配置

总结

uni-app 项目结构设计合理，既遵循了 Vue.js 的开发规范，又针对跨平台开发做了优化。理解和掌握项目结构是开发 uni-app 应用的基础，有助于：

提高开发效率
便于团队协作
降低维护成本
提升代码质量

建议在实际开发中，根据项目规模和团队需求，灵活调整目录结构，但要保持一致性和可维护性。

uni-app 项目结构详解 ​

概述 ​

基本项目结构 ​

核心文件详解 ​

1. pages.json - 页面路由配置 ​

基本结构 ​

主要配置项 ​

2. manifest.json - 应用配置清单 ​

基本结构 ​

主要配置项 ​

3. App.vue - 应用入口组件 ​

基本结构 ​

应用生命周期 ​

4. main.js - Vue 初始化入口 ​

基本结构 ​

主要功能 ​

目录结构详解 ​

pages 目录 ​

特点 ​

目录结构示例 ​

components 目录 ​

特点 ​

目录结构示例 ​

static 目录 ​

资源类型 ​

目录结构示例 ​

uni_modules 目录 ​

特点 ​

目录结构示例 ​

uniCloud 目录 ​

主要子目录 ​

目录结构示例 ​

特殊文件说明 ​

项目结构最佳实践 ​

1. 目录命名规范 ​

2. 组件分类管理 ​

3. 静态资源管理 ​

4. API 统一管理 ​

5. 状态管理 ​

完整项目结构示例 ​

总结 ​

相关链接 ​

uni-app 项目结构详解

概述

基本项目结构

核心文件详解

1. pages.json - 页面路由配置

基本结构

主要配置项

2. manifest.json - 应用配置清单

基本结构

主要配置项

3. App.vue - 应用入口组件

基本结构

应用生命周期

4. main.js - Vue 初始化入口

基本结构

主要功能

目录结构详解

pages 目录

特点

目录结构示例

components 目录

特点

目录结构示例

static 目录

资源类型

目录结构示例

uni_modules 目录

特点

目录结构示例

uniCloud 目录

主要子目录

目录结构示例

特殊文件说明

项目结构最佳实践

1. 目录命名规范

2. 组件分类管理

3. 静态资源管理

4. API 统一管理

5. 状态管理

完整项目结构示例

总结

相关链接