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安装 #
使用安装包:
- 访问 Node.js官网
- 下载LTS版本安装包
- 运行安装程序,按提示完成安装
使用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系统必须:
- 打开App Store
- 搜索"Xcode"
- 点击"获取"进行安装
- 安装完成后打开Xcode,接受许可协议
命令行工具:
bash
# 安装Xcode命令行工具
xcode-select --install
5.2 配置CocoaPods #
bash
# 安装CocoaPods
sudo gem install cocoapods
# 验证安装
pod --version
5.3 配置签名 #
- 打开Xcode
- 进入 Preferences → Accounts
- 添加Apple ID
- 选择团队
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 #
- 访问 Android Studio官网
- 下载对应平台的安装包
- 运行安装程序
安装必要组件:
- 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 创建模拟器 #
- 打开Android Studio
- 进入 Tools → Device Manager
- 点击 “Create Device”
- 选择设备类型
- 选择系统镜像
- 完成创建
命令行创建:
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