Uniapp全局配置教程

Rysxt_2026-02-26 12:16

Uniapp的全局配置是项目开发的基础，合理配置可以显著提升开发效率和用户体验。本教程将详细介绍Uniapp的各个全局配置文件及其常见配置项。

一、核心配置文件概述

Uniapp项目包含多个全局配置文件，每个文件负责不同的功能模块：

  1. ​pages.json​ - 页面路由与窗口配置
  2. ​manifest.json​ - 应用配置与原生能力
  3. ​App.vue​ - 应用入口与全局样式
  4. ​uni.scss​ - 全局样式变量
  5. ​package.json​ - 依赖管理与脚本配置

二、pages.json 详细配置

2.1 基本结构

复制代码 
{
  "pages": [],
  "globalStyle": {},
  "tabBar": {},
  "condition": {},
  "subPackages": []
}

2.2 pages 页面路由配置

pages数组中的每个对象代表一个页面，顺序决定页面优先级（首页为第一个）。

复制代码 
{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页",
        "enablePullDownRefresh": true,
        "backgroundColor": "#F8F8F8"
      }
    },
    {
      "path": "pages/user/user",
      "style": {
        "navigationBarTitleText": "个人中心",
        "navigationBarBackgroundColor": "#007AFF",
        "navigationBarTextStyle": "white"
      }
    }
  ]
}

​​常见配置项说明：​​

  • path: 页面路径，相对于项目根目录
  • navigationBarTitleText: 导航栏标题
  • navigationBarBackgroundColor: 导航栏背景色（默认#F7F7F7）
  • navigationBarTextStyle: 导航栏标题颜色（black/white）
  • backgroundColor: 窗口背景色
  • enablePullDownRefresh: 是否开启下拉刷新
  • onReachBottomDistance: 页面上拉触底事件触发时距页面底部距离（单位px）

2.3 globalStyle 全局窗口样式

复制代码 
{
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "我的应用",
    "navigationBarBackgroundColor": "#FFFFFF",
    "backgroundColor": "#F8F8F8",
    "backgroundColorTop": "#F8F8F8",
    "backgroundColorBottom": "#F8F8F8",
    "pageOrientation": "portrait",
    "rpxCalcMaxDeviceWidth": 960,
    "rpxCalcBaseDeviceWidth": 375,
    "rpxCalcIncludeWidth": 750
  }
}

​​重要配置说明：​​

  • pageOrientation: 屏幕方向设置，可选值：portrait（竖屏）、landscape（横屏）、auto（自动）
  • rpxCalc*系列：rpx计算基准配置，用于适配不同屏幕
  • backgroundColorTop/Bottom: 单独控制顶部和底部背景色

2.4 tabBar 底部导航栏

复制代码 
{
  "tabBar": {
    "color": "#7A7E83",
    "selectedColor": "#007AFF",
    "borderStyle": "black",
    "backgroundColor": "#FFFFFF",
    "list": [
      {
        "pagePath": "pages/index/index",
        "iconPath": "static/tabbar/home.png",
        "selectedIconPath": "static/tabbar/home-active.png",
        "text": "首页"
      },
      {
        "pagePath": "pages/user/user",
        "iconPath": "static/tabbar/user.png",
        "selectedIconPath": "static/tabbar/user-active.png",
        "text": "我的"
      }
    ],
    "position": "bottom",
    "fontSize": "10px",
    "iconWidth": "24px",
    "spacing": "3px"
  }
}

​​配置要点：​​

  • list数组最少2个、最多5个tab项
  • position: 可选bottom（底部）或top（顶部，仅微信小程序支持）
  • 图标建议尺寸：81px*81px，支持png/jpg格式
  • 微信小程序中tabBar图标不支持网络图片

2.5 subPackages 分包加载

复制代码 
{
  "subPackages": [
    {
      "root": "pagesA",
      "pages": [
        {
          "path": "page1/page1",
          "style": {}
        },
        {
          "path": "page2/page2",
          "style": {}
        }
      ]
    },
    {
      "root": "pagesB",
      "pages": [
        {
          "path": "page3/page3",
          "style": {}
        }
      ]
    }
  ]
}

​​分包优势：​​

  • 减少主包体积，加快首次加载速度
  • 按需加载，提升用户体验
  • 每个分包大小不超过2M（微信小程序限制）

2.6 preloadRule 分包预下载

复制代码 
{
  "preloadRule": {
    "pages/index/index": {
      "network": "wifi",
      "packages": ["pagesA"]
    }
  }
}

三、manifest.json 应用配置

3.1 基础配置

复制代码 
{
  "name": "MyApp",
  "appid": "__UNI__XXXXXX",
  "description": "应用描述",
  "versionName": "1.0.0",
  "versionCode": "100",
  "transformPx": false,
  "app-plus": {},
  "mp-weixin": {},
  "mp-alipay": {},
  "h5": {}
}

3.2 平台特定配置

​​微信小程序配置示例：​​

复制代码 
{
  "mp-weixin": {
    "appid": "wx1234567890",
    "setting": {
      "urlCheck": false,
      "es6": true,
      "postcss": true,
      "minified": true
    },
    "usingComponents": true,
    "permission": {
      "scope.userLocation": {
        "desc": "你的位置信息将用于小程序位置接口的效果展示"
      }
    },
    "requiredPrivateInfos": ["getLocation"]
  }
}

​​H5配置示例：​​

复制代码 
{
  "h5": {
    "title": "我的H5应用",
    "router": {
      "mode": "hash",
      "base": "/"
    },
    "template": "template.h5.html",
    "publicPath": "./",
    "sdkConfigs": {
      "maps": {}
    }
  }
}

​​App配置示例：​​

复制代码 
{
  "app-plus": {
    "distribute": {
      "android": {
        "permissions": [
          "<uses-permission android:name=\"android.permission.CAMERA\"/>"
        ]
      },
      "ios": {
        "UIRequiresFullScreen": true
      }
    },
    "splashscreen": {
      "alwaysShowBeforeRender": false,
      "waiting": true,
      "autoclose": true,
      "delay": 0
    }
  }
}

四、App.vue 全局应用配置

4.1 基本结构

复制代码 
<script>
export default {
  onLaunch: function(options) {
    console.log('App Launch', options)
    // 初始化操作
    this.initApp()
  },
  onShow: function(options) {
    console.log('App Show', options)
  },
  onHide: function() {
    console.log('App Hide')
  },
  methods: {
    initApp() {
      // 全局初始化逻辑
      uni.getSystemInfo({
        success: (res) => {
          this.globalData.systemInfo = res
        }
      })
    }
  },
  globalData: {
    systemInfo: null,
    userInfo: null,
    token: ''
  }
}
</script>

<style>
/* 全局样式 */
page {
  background-color: #f8f8f8;
  font-size: 28rpx;
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
}

/* 自定义全局类 */
.text-primary {
  color: #007AFF;
}

.bg-primary {
  background-color: #007AFF;
}
</style>

4.2 全局生命周期函数

  • onLaunch: 初始化完成时触发，全局只触发一次
  • onShow: 启动或从后台进入前台显示
  • onHide: 从前台进入后台
  • onError: 脚本错误监听
  • onPageNotFound: 页面不存在监听

4.3 全局数据管理

复制代码 
// 获取全局数据
const app = getApp()
console.log(app.globalData.userInfo)

// 设置全局数据
app.globalData.token = 'new_token'

五、uni.scss 全局样式变量

5.1 基础变量配置

复制代码 
/* 颜色变量 */
$uni-color-primary: #007AFF;
$uni-color-success: #4CD964;
$uni-color-warning: #F0AD4E;
$uni-color-error: #DD524D;
$uni-color-info: #909399;

/* 文字颜色 */
$uni-text-color: #333333;
$uni-text-color-inverse: #FFFFFF;
$uni-text-color-grey: #999999;
$uni-text-color-placeholder: #808080;
$uni-text-color-disable: #C0C0C0;

/* 背景颜色 */
$uni-bg-color: #FFFFFF;
$uni-bg-color-grey: #F8F8F8;
$uni-bg-color-hover: #F1F1F1;
$uni-bg-color-mask: rgba(0, 0, 0, 0.4);

/* 边框颜色 */
$uni-border-color: #E5E5E5;

/* 尺寸变量 */
$uni-font-size-sm: 24rpx;
$uni-font-size-base: 28rpx;
$uni-font-size-lg: 32rpx;
$uni-font-size-xl: 36rpx;
$uni-font-size-xxl: 44rpx;

/* 边框圆角 */
$uni-border-radius-sm: 4rpx;
$uni-border-radius-base: 6rpx;
$uni-border-radius-lg: 12rpx;
$uni-border-radius-circle: 50%;

/* 水平间距 */
$uni-spacing-row-sm: 10rpx;
$uni-spacing-row-base: 20rpx;
$uni-spacing-row-lg: 30rpx;

/* 垂直间距 */
$uni-spacing-col-sm: 8rpx;
$uni-spacing-col-base: 16rpx;
$uni-spacing-col-lg: 24rpx;

/* 透明度 */
$opacity-disabled: 0.3;

/* 文章场景相关 */
$uni-color-title: #2C405A;

5.2 自定义变量

复制代码 
/* 项目自定义主题色 */
$theme-color: #1890FF;
$theme-bg: #F0F2F5;

/* 组件变量 */
$button-height: 88rpx;
$input-height: 80rpx;

/* 响应式断点 */
$breakpoint-sm: 768px;
$breakpoint-md: 992px;
$breakpoint-lg: 1200px;

六、package.json 项目配置

6.1 依赖管理

复制代码 
{
  "name": "my-uniapp-project",
  "version": "1.0.0",
  "description": "Uniapp项目",
  "main": "main.js",
  "scripts": {
    "dev": "npm run dev:h5",
    "dev:h5": "uni -p h5",
    "dev:mp-weixin": "uni -p mp-weixin",
    "build:h5": "uni build -p h5",
    "build:mp-weixin": "uni build -p mp-weixin",
    "lint": "eslint . --ext .vue"
  },
  "dependencies": {
    "@dcloudio/uni-app": "^3.0.0",
    "@dcloudio/uni-h5": "^3.0.0",
    "vue": "^3.2.0",
    "vuex": "^4.0.0"
  },
  "devDependencies": {
    "@dcloudio/uni-cli-shared": "^3.0.0",
    "@dcloudio/types": "^3.0.0",
    "@dcloudio/vite-plugin-uni": "^3.0.0",
    "@vue/compiler-sfc": "^3.2.0",
    "eslint": "^8.0.0",
    "sass": "^1.32.0",
    "vite": "^4.0.0"
  },
  "uni-app": {
    "scripts": {}
  }
}

6.2 自定义编译条件

复制代码 
{
  "uni-app": {
    "scripts": {
      "custom-platform": {
        "title": "自定义平台",
        "browser": "",
        "env": {
          "UNI_PLATFORM": "h5"
        },
        "define": {
          "CUSTOM-CONST": true
        }
      }
    }
  }
}

七、环境变量配置

7.1 环境配置文件

创建 .env.development、.env.production 等文件：

复制代码 
# .env.development
VUE_APP_API_BASE=http://dev.api.com
VUE_APP_DEBUG=true
VUE_APP_VERSION=development

# .env.production
VUE_APP_API_BASE=https://api.production.com
VUE_APP_DEBUG=false
VUE_APP_VERSION=1.0.0

7.2 代码中使用环境变量

复制代码 
// 获取环境变量
const apiBase = process.env.VUE_APP_API_BASE
const isDebug = process.env.VUE_APP_DEBUG === 'true'

// 条件编译
// #ifdef H5
console.log('H5环境')
// #endif

// #ifdef MP-WEIXIN
console.log('微信小程序环境')
// #endif

八、最佳实践与注意事项

8.1 配置优化建议

  1. ​​路由配置优化​​

    • 首页放在pages数组第一位
    • 合理使用分包，主包控制在2M以内
    • 使用preloadRule预加载常用分包

  2. ​​样式配置建议​​

    • 统一使用uni.scss变量管理颜色和尺寸
    • 合理设置rpx计算基准，确保多端适配
    • 使用条件编译处理平台差异样式

  3. ​​性能优化配置​​

    复制代码 
    {
  "globalStyle": {
    "renderingMode": "seperated",
    "pageOrientation": "portrait",
    "rpxCalcMaxDeviceWidth": 960,
    "rpxCalcBaseDeviceWidth": 375
  }
}

8.2 常见问题解决

  1. ​​页面白屏问题​​

    • 检查pages.json中页面路径是否正确
    • 确认分包配置是否合理
    • 查看控制台错误信息

  2. ​​样式不生效​​

    • 检查uni.scss变量引用是否正确
    • 确认样式选择器优先级
    • 使用!important调试

  3. ​​跨平台兼容性​​

    • 使用条件编译处理平台差异
    • 测试各平台特有API的可用性
    • 关注各平台审核规范差异

8.3 调试技巧

  1. ​​使用Chrome开发者工具​​

    • 查看网络请求
    • 调试JavaScript代码
    • 分析性能瓶颈

  2. ​​微信开发者工具​​

    • 模拟器调试
    • 真机调试
    • 性能分析

  3. ​​HBuilderX调试​​

    • 断点调试
    • 控制台输出
    • 实时预览

九、高级配置技巧

9.1 自定义导航栏

复制代码 
{
  "globalStyle": {
    "navigationStyle": "custom",
    "navigationBarTextStyle": "white",
    "navigationBarBackgroundColor": "#007AFF"
  }
}

9.2 动态修改配置

复制代码 
// 动态修改页面标题
uni.setNavigationBarTitle({
  title: '新标题'
})

// 动态修改tabBar
uni.setTabBarItem({
  index: 0,
  text: '新首页',
  iconPath: 'static/new-icon.png',
  selectedIconPath: 'static/new-icon-active.png'
})

9.3 国际化配置

复制代码 
// 创建i18n配置文件
// locales/zh-CN.json
{
  "home": "首页",
  "user": "我的"
}

// locales/en-US.json
{
  "home": "Home",
  "user": "My"
}

// 在App.vue中初始化
import en from './locales/en-US.json'
import zh from './locales/zh-CN.json'

export default {
  globalData: {
    locales: { en, zh },
    currentLocale: 'zh-CN'
  }
}

总结

Uniapp的全局配置系统非常完善，通过合理配置可以：

  1. 统一应用风格和体验
  2. 优化应用性能
  3. 简化多端适配工作
  4. 提高开发效率

建议在实际开发中根据项目需求灵活组合使用各种配置，并建立统一的配置规范，确保团队协作效率和代码质量。定期检查官方文档更新，及时了解新特性和最佳实践。

相关推荐
阿珊和她的猫1 小时前
深入理解与使用 Cookie：Web 开发中的关键机制
前端·状态模式
用户547487596221 小时前
webpack代码分割
前端
简离1 小时前
Ant Design Form.Item 多元素场景踩坑指南：自定义onChange导致表单值同步失败解决方案
前端·ant design
JunjunZ1 小时前
uniapp实现图片压缩并上传
前端·vue.js
简离1 小时前
Nginx限流触发原因排查及前端优化方案
前端·nginx
Jydud1 小时前
高性能直播弹幕系统实现：从 Canvas 2D 到 WebGPU
前端·javascript·vue.js
你怎么知道我是队长1 小时前
前端学习---HTML---块元素和行内元素
前端·学习·html
vivo互联网技术1 小时前
深度解析悟空系统多机房部署共线改造
前端·npm·多语言·共线改造·多机房
热门推荐
01GitHub 镜像站点02Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services03【OpenClaw 本地实战 Ep.3】突破瓶颈：强制修改 openclaw.json 解锁 32k 上下文记忆04AI Agent 平台横评：ZeroClaw vs OpenClaw vs Nanobot05OpenClaw 使用和管理 MCP 完全指南06Clawdbot部署教程：解决‘gateway token missing’授权问题的完整步骤07AI 规范驱动开发“三剑客”深度对比：Spec-Kit、Kiro 与 OpenSpec 实战指南08OpenClaw 安装之（三）DeepSeek模型接入配置和详细配置参数09AI agent：介绍 ZeroClaw 安装，使用10让 Trae IDE 智能体 “读懂”文档 Excel+PDF+DOCX ：mcp-documents-reader 工具使用指南