uni-app 环境与工具配置指南

uni-app 环境与工具配置指南

1. 基础环境准备

• Node.js
  需安装 $v14.18.0$ 或更高版本（LTS 推荐）
  官网下载
• 包管理器
  二选一安装：
  • npm（Node.js 自带）
  • yarn（推荐更快的依赖管理）

    npm install -g yarn
    

2. 开发工具选择

• 官方推荐
  HBuilderX（专为 uni-app 优化）
  • 下载地址：HBuilderX 官网
  • 特性：
    • 内置 uni-app 模板
    • 实时预览/调试
    • 一键打包多端
• 备选方案
  VS Code + 插件组合：
  1. 安装插件：
     • uni-app-snippets（代码片段）
     • uni-helper（API 提示）
     • eslint-plugin-uni（语法检查）
  2. 配置工作区：

     // .vscode/settings.json
     {
       "eslint.validate": ["javascript", "vue"],
       "vetur.validation.template": false
     }
     

3. 项目创建与依赖安装

# 通过 CLI 创建项目（需全局安装 @dcloudio/uni-app-cli）
npm install -g @dcloudio/uni-app-cli
uni create -t default my-project

# 进入项目并安装依赖
cd my-project
yarn install  # 或 npm install

4. 平台工具链配置

目标平台	必需工具	关键配置步骤
微信小程序	微信开发者工具	设置 → 安全 → 开启服务端口
Android	Android Studio + SDK Platform 30+	配置 ANDROID_HOME 环境变量
iOS	Xcode 13+	证书签名配置
H5	无需额外工具	直接运行 yarn dev:h5

5. 调试与运行命令

# 启动开发服务器（按平台选择）
yarn dev:%PLATFORM%  # %PLATFORM% 替换为：mp-weixin/h5/app-plus

# 生产环境打包
yarn build:%PLATFORM%

6. 常见问题解决

• 微信开发者工具无法连接
  检查是否开启端口：微信开发者工具 → 设置 → 安全 → 服务端口（开启）
• Android 真机调试失败
  执行 adb devices 确认设备连接，并开启 USB 调试模式
• HBuilderX 模拟器卡顿
  升级到最新版，或在 manifest.json 中关闭 SourceMap：

  "devServer": { "sourceMap": false }
  

提示：首次运行 Android/iOS 项目需先配置原生平台依赖：

yarn add @dcloudio/uni-app-plus  # Android
yarn add @dcloudio/uni-app-ios  # iOS