📖 本指南专门针对 Uniapp 端（移动端）的二次开发，教你如何开发支持H5、微信小程序、APP等多端的移动应用。

📋 目录

1. 技术栈介绍
2. 开始之前的准备
3. 首次安装配置
4. 环境文件配置
5. H5开发模式
6. 微信小程序开发
7. APP开发
8. 生产环境打包
9. 开发技巧
10. 常见问题解决
11. 快速参考

技术栈介绍

Uniapp 端使用的技术栈：

支持的平台：

✅ H5（网页版）
✅ 微信小程序
✅ 支付宝小程序
✅ Android APP
✅ iOS APP
✅ 其他小程序平台（QQ、百度、头条等）
核心功能组件：
✅ Markdown 渲染：markdown-it
✅ PDF 预览：pdfjs-dist
✅ Excel 处理：xlsx
✅ 语音录制：recorder-core
✅ 视频播放：video.js
✅ 分页组件：z-paging

开始之前的准备

2.1 检查 Node.js 版本

Uniapp 端推荐使用 Node 16 或更高版本。

检查当前版本：
node -v

如果版本低于 16，请先升级：

下载地址：https://nodejs.org/
选择 LTS 版本
2.2 选择包管理器

推荐使用 npm（Node.js 自带）。

2.3 安装开发工具

根据你要开发的平台，需要安装对应的工具：

H5 开发（推荐新手）：

只需要浏览器，无需额外工具
微信小程序开发：
下载并安装微信开发者工具
APP 开发：
下载并安装 HBuilderX（uni-app 官方 IDE）

首次安装配置

步骤 1：进入 Uniapp 端目录

在项目根目录下

cd uniapp

步骤 2：安装依赖包

使用 npm 安装（首次会比较慢，请耐心等待）

npm install

⚠️ 重要提示：

安装前务必确认 Node 版本是 16+
Uniapp 依赖较多，安装时间可能较长（5-15分钟）
如果安装失败，请查看本文档「常见问题」部分

安装成功的标志：

终端没有报错
生成了 node_modules 文件夹
生成了 package-lock.json 文件
步骤 3：复制环境配置文件

Uniapp 端需要配置 2 个环境文件：

在 uniapp 目录下执行以下命令（Windows 系统）

1. 复制开发环境配置

copy .env.development.example .env.development

2. 复制生产环境配置

copy .env.production.example .env.production

Mac/Linux 系统：
cp .env.development.example .env.development
cp .env.production.example .env.production

💡 文件说明：

.env.development → 开发环境配置（本地开发用）
.env.production → 生产环境配置（打包上线用）

环境文件配置

4.1 配置文件 1：.env.development（开发环境）

打开 uniapp/.env.development，配置后端 API 地址：

后端 API 请求地址

VITE_APP_BASE_URL = 'http://你的后端地址'

配置示例：

示例 1：本地开发（后端在本地运行）
VITE_APP_BASE_URL = 'http://127.0.0.1:8000'

示例 2：连接测试服务器
VITE_APP_BASE_URL = 'http://test.yourdomain.com'

示例 3：连接线上服务器
VITE_APP_BASE_URL = 'https://api.yourdomain.com'

🎯 重点：这个地址必须是你的后端服务器地址，开发时所有 API 请求都会发送到这里。

4.2 配置文件 2：.env.production（生产环境）

打开 uniapp/.env.production，配置生产环境的 API 地址：

生产环境的后端 API 地址

VITE_APP_BASE_URL = ''

配置说明：

留空（推荐）：
VITE_APP_BASE_URL = ''

H5 打包后会自动使用当前域名作为 API 地址
指定地址：
VITE_APP_BASE_URL = 'https://api.yourdomain.com'
小程序和 APP 必须指定完整的后端地址
H5 如果后端不在同一域名下，也需要指定

H5开发模式

H5 开发最简单，推荐新手从这里开始。

5.1 启动 H5 开发服务器

在 uniapp 目录下执行

npm run dev:h5

5.2 访问 H5 页面

启动成功后，终端会显示：

VITE v4.1.4 ready in 2345 ms

➜ Local: http://localhost:8991/
➜ Network: http://192.168.1.100:8991/

打开浏览器访问：http://localhost:8991

5.3 H5 开发特点

✅ 热重载：修改代码后自动刷新
✅ 实时预览：可以立即看到效果
✅ 浏览器调试：可以使用 Chrome DevTools
✅ 快速开发：无需安装额外工具

💡 提示：H5 开发适合快速验证功能，但要注意某些功能在小程序和 APP 上可能有差异。

微信小程序开发

6.1 准备工作

安装微信开发者工具

下载地址：https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html
安装并登录

获取小程序 AppID

如果没有，可以使用测试号
6.2 启动小程序开发

第 1 步：编译小程序代码

在 uniapp 目录下执行

npm run dev:mp-weixin

编译成功后，会在 uniapp/dist/dev/mp-weixin 目录下生成小程序代码。

第 2 步：打开微信开发者工具

启动微信开发者工具
选择「导入项目」
填写项目信息：
- 项目目录：选择 uniapp/dist/dev/mp-weixin
- AppID：填写你的小程序 AppID（或选择测试号）
- 项目名称：随意填写
点击「导入」
第 3 步：开始开发

在代码编辑器（VS Code）中修改代码
修改后会自动重新编译
微信开发者工具会自动刷新（需要开启「自动编译」）
6.3 小程序开发注意事项

域名配置

小程序必须配置合法域名：

登录微信公众平台：https://mp.weixin.qq.com/
进入「开发」-「开发管理」-「开发设置」
配置「服务器域名」
开发阶段可以勾选「不校验合法域名」：
在微信开发者工具中
点击「详情」
勾选「不校验合法域名、web-view（业务域名）、TLS 版本以及 HTTPS 证书」

条件编译

针对小程序特殊处理：

APP开发

7.1 准备工作

安装 HBuilderX：

下载地址：https://www.dcloud.io/hbuilderx.html
下载「标准版」或「App 开发版」
7.2 使用 HBuilderX 开发

第 1 步：导入项目

打开 HBuilderX
点击「文件」-「导入」-「从本地目录导入」
选择 uniapp 目录
第 2 步：配置 manifest.json

在 uniapp/src/manifest.json 中配置 APP 信息：

{
"name": "应用名称",
"appid": "你的应用ID",
"description": "应用描述",
"versionName": "1.0.0",
"versionCode": "100",

"app-plus": {
"usingComponents": true,
"nvueStyleCompiler": "uni-app",
"compilerVersion": 3,
"splashscreen": {
"alwaysShowBeforeRender": true,
"waiting": true,
"autoclose": true,
"delay": 0
},
"modules": {},
"distribute": {
"android": {
"permissions": [
"<uses-permission android:name="android.permission.INTERNET"/>",
"<uses-permission android:name="android.permission.CAMERA"/>",
"<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>"
]
},
"ios": {},
"sdkConfigs": {}
}
}
}

第 3 步：运行到手机

真机调试：

手机用 USB 连接电脑
手机开启「开发者选项」和「USB 调试」
在 HBuilderX 中点击「运行」-「运行到手机或模拟器」
选择你的手机
模拟器调试：
安装 Android 模拟器
在 HBuilderX 中选择模拟器运行

生产环境打包

8.1 H5 打包

第 1 步：配置生产环境

编辑 uniapp/.env.production：
VITE_APP_BASE_URL = 'https://api.yourdomain.com'

第 2 步：执行打包命令

在 uniapp 目录下执行

npm run build:h5

第 3 步：部署

打包后的文件在 server/public/mobile/ 目录下，上传到服务器即可。

访问地址：
https://yourdomain.com/mobile/

8.2 微信小程序打包

第 1 步：配置生产环境

编辑 uniapp/.env.production：
VITE_APP_BASE_URL = 'https://api.yourdomain.com'

第 2 步：执行打包命令

在 uniapp 目录下执行

npm run build:mp-weixin

打包后的文件在 server/public/weapp/ 目录下。

第 3 步：上传到微信

打开微信开发者工具
导入 server/public/weapp/ 目录
点击「上传」按钮
填写版本号和备注
提交审核
第 4 步：审核发布
登录微信公众平台
进入「版本管理」
提交审核
审核通过后发布

8.3 APP 打包

使用 HBuilderX 打包

Android 打包：

在 HBuilderX 中打开项目
点击「发行」-「原生 App-云打包」
选择 Android 平台
配置签名证书
点击「打包」
等待打包完成（通常需要 5-15 分钟）
下载 APK 文件
iOS 打包：
需要 Apple 开发者账号
配置证书和描述文件
在 HBuilderX 中选择 iOS 打包
下载 IPA 文件
通过 App Store Connect 上传

开发技巧

9.1 创建新页面

第 1 步：创建页面文件

在 uniapp/src/pages/ 下创建页面文件：

.article-detail { padding: 30rpx; .title { font-size: 40rpx; font-weight: bold; margin-bottom: 20rpx; } .content { font-size: 28rpx; line-height: 1.6; color: #333; } .footer { display: flex; justify-content: space-around; margin-top: 40rpx; button { flex: 1; margin: 0 10rpx; } } }

第 2 步：配置页面路由

编辑 uniapp/src/pages.json：

{
"pages": [
// ... 其他页面

{
"path": "pages/article/detail",
"style": {
"navigationBarTitleText": "文章详情",
"navigationBarBackgroundColor": "#ffffff",
"navigationBarTextStyle": "black"
}
}
]
}

第 3 步：跳转到新页面

9.2 调用后端 API

创建 API 文件

在 uniapp/src/api/ 下创建 API 接口文件：

// uniapp/src/api/article.ts
import request from '@/utils/request'

// 获取文章列表
export function getArticleList(params: any) {
return request.get('/api/article/list', params)
}

// 获取文章详情
export function getArticleDetail(id: number) {
return request.get('/api/article/detail', { id })
}

// 点赞文章
export function likeArticle(id: number) {
return request.post('/api/article/like', { id })
}

在页面中使用

9.3 使用状态管理（Pinia）

创建 Store

在 uniapp/src/stores/ 下创建状态管理文件：

// uniapp/src/stores/user.ts
import { defineStore } from 'pinia'

export const useUserStore = defineStore('user', {
state: () => ({
userInfo: null,
token: '',
isLogin: false
}),

getters: {
userName: (state) => state.userInfo?.name || '游客'
},

actions: {
// 设置 Token
setToken(token: string) {
this.token = token
this.isLogin = true
// 存储到本地
uni.setStorageSync('token', token)
},

// 设置用户信息
setUserInfo(info: any) {
this.userInfo = info
uni.setStorageSync('userInfo', info)
},

// 退出登录
logout() {
this.token = ''
this.userInfo = null
this.isLogin = false
uni.removeStorageSync('token')
uni.removeStorageSync('userInfo')
}
}
})

在组件中使用

9.4 条件编译（跨端适配）

不同平台的差异处理：

/* #ifdef H5 */ /* H5 专属样式 */ .h5-style { color: red; } /* #endif */ /* #ifdef MP-WEIXIN */ /* 微信小程序专属样式 */ .weixin-style { color: blue; } /* #endif */

9.5 常用 API

页面跳转

// 保留当前页面，跳转到应用内的某个页面
uni.navigateTo({
url: '/pages/detail/detail?id=123'
})

// 关闭当前页面，跳转到应用内的某个页面
uni.redirectTo({
url: '/pages/index/index'
})

// 关闭所有页面，打开到应用内的某个页面
uni.reLaunch({
url: '/pages/login/login'
})

// 跳转到 tabBar 页面
uni.switchTab({
url: '/pages/index/index'
})

// 返回上一页
uni.navigateBack({
delta: 1 // 返回的页面数
})

数据存储

// 存储数据
uni.setStorageSync('key', 'value')

// 获取数据
const value = uni.getStorageSync('key')

// 删除数据
uni.removeStorageSync('key')

// 清空所有数据
uni.clearStorageSync()

// 异步存储
uni.setStorage({
key: 'key',
data: 'value',
success() {
console.log('存储成功')
}
})

提示框

// 显示消息提示框
uni.showToast({
title: '操作成功',
icon: 'success',
duration: 2000
})

// 显示加载提示框
uni.showLoading({
title: '加载中...'
})

// 隐藏加载提示框
uni.hideLoading()

// 显示模态对话框
uni.showModal({
title: '提示',
content: '确定要删除吗？',
success(res) {
if (res.confirm) {
console.log('用户点击确定')
}
}
})

常见问题解决

问题 1：npm install 失败

解决方法：

清除缓存重新安装

npm cache clean --force
rmdir /s /q node_modules
del package-lock.json
npm install

问题 2：小程序白屏

可能原因：

API 域名未配置
代码包过大
解决方法：

在微信公众平台配置合法域名
开发时勾选「不校验合法域名」
检查代码包大小，考虑分包加载

问题 3：H5 图片不显示

解决方法：

问题 4：条件编译不生效

解决方法：

确保注释格式正确，不要有多余空格：

问题 5：真机调试连接失败

解决方法：

确保手机和电脑在同一网络
检查手机是否开启 USB 调试
重启 HBuilderX
重新连接手机

快速参考

11.1 常用命令

安装依赖

npm install

H5 开发

npm run dev:h5

微信小程序开发

npm run dev:mp-weixin

H5 打包

npm run build:h5

微信小程序打包

npm run build:mp-weixin

其他平台

npm run dev:mp-alipay # 支付宝小程序
npm run dev:mp-qq # QQ 小程序
npm run dev:mp-baidu # 百度小程序
npm run dev:mp-toutiao # 字节跳动小程序

11.2 配置文件位置

文件
路径
说明
开发环境配置
uniapp/.env.development
本地开发用
生产环境配置
uniapp/.env.production
打包上线用
页面配置
uniapp/src/pages.json
页面路由配置
APP 配置
uniapp/src/manifest.json
APP 基本信息
Vite 配置
uniapp/vite.config.ts
构建工具配置
包管理配置
uniapp/package.json
依赖和脚本

11.3 重要目录结构

uniapp/
├── src/
│ ├── pages/ # 页面文件
│ ├── components/ # 公共组件
│ ├── api/ # API 接口
│ ├── stores/ # 状态管理
│ ├── utils/ # 工具函数
│ ├── static/ # 静态资源
│ ├── App.vue # 根组件
│ ├── main.ts # 入口文件
│ ├── pages.json # 页面配置
│ └── manifest.json # APP 配置
├── .env.development # 开发环境配置
├── .env.production # 生产环境配置
└── package.json # 项目配置

11.4 开发流程速查

H5 开发：

cd uniapp
npm install
copy .env.development.example .env.development
编辑 .env.development
npm run dev:h5
访问 http://localhost:8991

微信小程序开发：

cd uniapp
npm install
npm run dev:mp-weixin
打开微信开发者工具
导入 dist/dev/mp-weixin 目录

打包部署：

编辑 .env.production
npm run build:h5（或 build:mp-weixin）
上传对应的打包文件

🎯 总结

本指南涵盖了 Uniapp 端二次开发的所有关键步骤：

✅ 环境准备（Node.js、开发工具）
✅ 安装配置（依赖、环境文件）
✅ 多端开发（H5、小程序、APP）
✅ 打包部署（各平台打包）
✅ 开发技巧（页面创建、API调用、跨端适配）
✅ 问题解决（常见错误处理）
推荐学习资源：

uni-app 官方文档：https://uniapp.dcloud.net.cn/
Vue 3 官方文档：https://cn.vuejs.org/
微信小程序文档：https://developers.weixin.qq.com/miniprogram/dev/framework/
祝你开发顺利！🚀

Uniapp端二次开发指南

在项目根目录下

使用 npm 安装（首次会比较慢，请耐心等待）

在 uniapp 目录下执行以下命令（Windows 系统）

1. 复制开发环境配置

2. 复制生产环境配置

后端 API 请求地址

生产环境的后端 API 地址

在 uniapp 目录下执行

在 uniapp 目录下执行

在 uniapp 目录下执行

在 uniapp 目录下执行

清除缓存重新安装

安装依赖

H5 开发

微信小程序开发

H5 打包

微信小程序打包

其他平台