Ionic环境搭建 #

一、环境要求 #

1.1 系统要求 #

平台 最低要求
macOS 10.15 (Catalina) 或更高
Windows Windows 10 或更高
Linux Ubuntu 18.04+ 或同等版本

1.2 软件要求 #

软件 版本要求 用途
Node.js 18.x LTS 或更高 JavaScript运行时
npm 9.x 或更高 包管理器
Git 2.x 版本控制
Ionic CLI 最新版 Ionic命令行工具

1.3 原生开发要求 #

iOS开发:

软件 要求
Xcode 14.0 或更高
CocoaPods 1.10+
macOS 必须

Android开发:

软件 要求
JDK 17 或更高
Android Studio 最新版
Android SDK API 22+
Gradle 8.0+

二、安装Node.js #

2.1 macOS安装 #

使用Homebrew安装:

bash
# 安装Homebrew(如果未安装)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装Node.js
brew install node

# 验证安装
node -v
npm -v

使用nvm安装(推荐):

bash
# 安装nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 安装LTS版本
nvm install --lts

# 使用LTS版本
nvm use --lts

# 验证安装
node -v
npm -v

2.2 Windows安装 #

使用安装包:

  1. 访问 Node.js官网
  2. 下载LTS版本安装包
  3. 运行安装程序,按提示完成安装

使用Chocolatey:

powershell
# 安装Chocolatey(如果未安装)
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))

# 安装Node.js
choco install nodejs-lts

# 验证安装
node -v
npm -v

2.3 Linux安装 #

Ubuntu/Debian:

bash
# 使用NodeSource
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证安装
node -v
npm -v

CentOS/RHEL:

bash
# 使用NodeSource
curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -
sudo yum install -y nodejs

# 验证安装
node -v
npm -v

三、安装Ionic CLI #

3.1 全局安装 #

bash
# 安装Ionic CLI
npm install -g @ionic/cli

# 验证安装
ionic -v

# 查看帮助
ionic --help

3.2 更新Ionic CLI #

bash
# 更新到最新版本
npm update -g @ionic/cli

# 查看当前版本
ionic --version

3.3 Ionic CLI常用命令 #

命令 说明
ionic start 创建新项目
ionic serve 启动开发服务器
ionic build 构建应用
ionic generate 生成页面/组件/服务等
ionic cap add 添加原生平台
ionic cap run 运行原生应用
ionic lab 启动Ionic Lab
ionic info 查看环境信息

四、安装Capacitor #

4.1 Capacitor简介 #

Capacitor是Ionic官方的跨平台原生运行时,用于将Web应用打包为原生应用。

text
Capacitor架构
    │
    ├── Core - 核心运行时
    │
    ├── CLI - 命令行工具
    │
    └── Plugins - 原生插件
        ├── Official - 官方插件
        └── Community - 社区插件

4.2 Capacitor CLI安装 #

bash
# Capacitor通常随Ionic项目安装
# 也可以全局安装
npm install -g @capacitor/cli

# 验证安装
npx cap --version

4.3 Capacitor常用命令 #

命令 说明
npx cap init 初始化Capacitor
npx cap add ios 添加iOS平台
npx cap add android 添加Android平台
npx cap copy 复制Web资源到原生项目
npx cap sync 同步Web资源和插件
npx cap open ios 打开Xcode
npx cap open android 打开Android Studio
npx cap run ios 运行iOS应用
npx cap run android 运行Android应用

五、配置iOS开发环境 #

5.1 安装Xcode #

macOS系统必须:

  1. 打开App Store
  2. 搜索"Xcode"
  3. 点击"获取"进行安装
  4. 安装完成后打开Xcode,接受许可协议

命令行工具:

bash
# 安装Xcode命令行工具
xcode-select --install

5.2 配置CocoaPods #

bash
# 安装CocoaPods
sudo gem install cocoapods

# 验证安装
pod --version

5.3 配置签名 #

  1. 打开Xcode
  2. 进入 Preferences → Accounts
  3. 添加Apple ID
  4. 选择团队

5.4 模拟器配置 #

bash
# 查看可用模拟器
xcrun simctl list devices

# 启动模拟器
open -a Simulator

# Ionic运行iOS模拟器
ionic cap run ios -l --external

六、配置Android开发环境 #

6.1 安装JDK #

macOS:

bash
# 使用Homebrew
brew install openjdk@17

# 配置环境变量
sudo ln -sfn /opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-17.jdk

Windows:

powershell
# 使用Chocolatey
choco install openjdk17

# 或下载安装包
# https://adoptium.net/

验证安装:

bash
java -version
javac -version

6.2 安装Android Studio #

  1. 访问 Android Studio官网
  2. 下载对应平台的安装包
  3. 运行安装程序

安装必要组件:

  • Android SDK
  • Android SDK Platform-Tools
  • Android SDK Build-Tools
  • Android Emulator

6.3 配置环境变量 #

macOS/Linux (~/.zshrc 或 ~/.bash_profile):

bash
# Android SDK路径
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools
export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin

Windows(系统环境变量):

text
ANDROID_HOME=C:\Users\用户名\AppData\Local\Android\Sdk
Path添加:
  %ANDROID_HOME%\emulator
  %ANDROID_HOME%\platform-tools
  %ANDROID_HOME%\cmdline-tools\latest\bin

6.4 创建模拟器 #

  1. 打开Android Studio
  2. 进入 Tools → Device Manager
  3. 点击 “Create Device”
  4. 选择设备类型
  5. 选择系统镜像
  6. 完成创建

命令行创建:

bash
# 查看可用镜像
sdkmanager --list

# 创建模拟器
avdmanager create avd -n MyDevice -k "system-images;android-33;google_apis;x86_64"

# 启动模拟器
emulator -avd MyDevice

七、IDE配置 #

7.1 VS Code推荐扩展 #

扩展 用途
Ionic Ionic代码提示
Capacitor Capacitor支持
Angular Angular支持(如使用Angular)
ES7+ React/Redux React支持(如使用React)
Vetur Vue支持(如使用Vue)
TypeScript TypeScript支持
Prettier 代码格式化
ESLint 代码检查

7.2 VS Code配置 #

json
// settings.json
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "typescript.preferences.importModuleSpecifier": "relative",
  "ionic.preview.port": 8100
}

7.3 推荐设置 #

json
// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "chrome",
      "request": "launch",
      "name": "Ionic Serve",
      "url": "http://localhost:8100",
      "webRoot": "${workspaceFolder}"
    }
  ]
}

八、验证环境 #

8.1 检查环境信息 #

bash
# 查看Ionic环境信息
ionic info

预期输出:

text
Ionic:

   Ionic CLI                     : 7.x.x
   Ionic Framework               : @ionic/angular 8.x.x
   @angular-devkit/build-angular : 17.x.x
   @angular-devkit/schematics    : 17.x.x
   @angular/cli                  : 17.x.x
   @ionic/angular-toolkit        : 11.x.x

Capacitor:

   Capacitor CLI      : 6.x.x
   @capacitor/core    : 6.x.x

Utility:

   cordova-res : not installed globally
   native-run  : 2.x.x

System:

   NodeJS : v20.x.x
   npm    : 10.x.x
   OS     : macOS Sonoma
   Xcode  : Xcode 15.x

8.2 创建测试项目 #

bash
# 创建测试项目
ionic start testApp blank --type=angular

# 进入项目目录
cd testApp

# 启动开发服务器
ionic serve

8.3 测试原生构建 #

bash
# 添加iOS平台
ionic cap add ios

# 添加Android平台
ionic cap add android

# 构建并同步
ionic build
npx cap sync

# 运行iOS
ionic cap run ios

# 运行Android
ionic cap run android

九、常见问题 #

9.1 Node.js版本问题 #

bash
# 使用nvm切换Node版本
nvm install 18
nvm use 18

# 或使用nvm-for-windows(Windows)

9.2 权限问题 #

bash
# macOS/Linux修复npm权限
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

9.3 网络问题 #

bash
# 设置npm镜像
npm config set registry https://registry.npmmirror.com

# 设置Ionic镜像
ionic config set -g npmClient npm

9.4 Xcode问题 #

bash
# 重置Xcode命令行工具
sudo xcode-select --reset

# 重新安装命令行工具
sudo xcode-select --install

9.5 Android SDK问题 #

bash
# 接受Android SDK许可
sdkmanager --licenses

# 更新SDK
sdkmanager --update

十、开发工具推荐 #

10.1 调试工具 #

工具 用途
Chrome DevTools Web调试
Safari Web Inspector iOS调试
Chrome://inspect Android调试
React DevTools React调试
Vue DevTools Vue调试

10.2 辅助工具 #

工具 用途
Postman API测试
JSON Viewer JSON格式化
Color Picker 颜色选择
Icon Generator 图标生成

十一、总结 #

11.1 环境检查清单 #

  • [ ] Node.js 18+ 已安装
  • [ ] npm 9+ 已安装
  • [ ] Ionic CLI 已安装
  • [ ] Capacitor CLI 已安装
  • [ ] Git 已安装
  • [ ] Xcode 已安装(macOS)
  • [ ] Android Studio 已安装
  • [ ] 环境变量已配置
  • [ ] 测试项目运行成功

11.2 下一步 #

环境搭建完成后,让我们创建 第一个应用,开始你的Ionic开发之旅!

最后更新:2026-03-28