系统要求

硬件要求

• 内存：8GB RAM（推荐 16GB）
• 硬盘：至少 10GB 可用空间
• 处理器：Intel 或 Apple Silicon (M1/M2/M3)

软件要求

• macOS 版本：10.15 (Catalina) 或更高版本
• Xcode：建议安装最新版本（用于 iOS 相关开发）

安装 DevEco Studio

1. 下载 DevEco Studio

访问华为开发者官网下载最新版本：

https://developer.harmonyos.com/cn/develop/deveco-studio

2. 安装步骤

1. 双击下载的** **.dmg 文件
2. 将 DevEco Studio 拖动到 Applications 文件夹
3. 首次打开时，可能需要在** **系统偏好设置 > 安全性与隐私 中允许运行

3. 初始化配置

首次启动 DevEco Studio 时：

# 选择安装路径（建议使用默认路径）
~/Library/Huawei/DevEcoStudio4.0

# SDK 默认安装路径
~/Library/Huawei/Sdk

环境变量配置

1. 确定 Shell 类型

# 查看当前使用的 Shell
echo $SHELL

# 如果输出 /bin/zsh，编辑 ~/.zshrc
# 如果输出 /bin/bash，编辑 ~/.bash_profile

2. 配置环境变量

使用 Zsh (macOS Catalina 及以后版本默认)

# 打开配置文件
nano ~/.zshrc

# 或使用 vim
vim ~/.zshrc

添加以下内容：

# HarmonyOS SDK 环境变量
export HARMONYOS_HOME=~/Library/Huawei/Sdk
export HOS_SDK_HOME=$HARMONYOS_HOME/HarmonyOS-NEXT-DB6

# HDC 工具路径
export HDC_HOME=$HOS_SDK_HOME/base/toolchains
export PATH=$PATH:$HDC_HOME

# Node.js 路径（DevEco Studio 内置）
export DEVECO_NODE_HOME=~/Library/Huawei/DevEcoStudio4.0/tools/node
export PATH=$PATH:$DEVECO_NODE_HOME/bin

# OHPM 包管理器路径
export OHPM_HOME=~/Library/Huawei/DevEcoStudio4.0/tools/ohpm
export PATH=$PATH:$OHPM_HOME/bin

# Java 环境（如果 DevEco Studio 自带）
export JAVA_HOME=~/Library/Huawei/DevEcoStudio4.0/jbr
export PATH=$PATH:$JAVA_HOME/bin

使用 Bash

# 打开配置文件
nano ~/.bash_profile

添加相同的环境变量内容。

3. 使配置生效

# 对于 zsh
source ~/.zshrc

# 对于 bash
source ~/.bash_profile

SDK 配置

1. 打开 SDK Manager

在 DevEco Studio 中：

• 菜单栏：DevEco Studio > Preferences (或按** **⌘,)
• 选择** **HarmonyOS SDK

2. 安装必要组件

确保安装以下组件：

✅ HarmonyOS SDK
  ├── API Version 9 (推荐)
  ├── API Version 10
  └── API Version 11 (最新)

✅ SDK Tools
  ├── Toolchains
  ├── Previewer
  └── System-image (用于模拟器)

✅ SDK Platforms
  └── 选择目标设备平台

3. 配置 SDK 路径

# 默认 SDK 路径
~/Library/Huawei/Sdk

# 可以在 Preferences 中自定义路径

验证安装

1. 验证环境变量

# 检查 HarmonyOS 环境变量
echo $HARMONYOS_HOME
# 输出：/Users/[用户名]/Library/Huawei/Sdk

# 检查 HDC 工具
hdc version
# 输出：HDC Version: x.x.x

# 检查 OHPM
ohpm -v
# 输出：ohpm version x.x.x

# 检查 Node.js
node -v
# 输出：v14.x.x 或更高版本

2. 创建测试项目

# 使用命令行创建项目（可选）
ohpm init hello-harmony

# 或在 DevEco Studio 中创建
# File > New > Create Project

3. 运行设备检测

# 列出已连接设备
hdc list targets

# 查看设备信息
hdc shell getprop ro.product.model

常见问题

Q1: 权限问题

# 如果遇到权限错误，修改文件权限
chmod +x ~/Library/Huawei/DevEcoStudio4.0/bin/devecostudio.sh

Q2: Apple Silicon (M1/M2/M3) 兼容性

# 安装 Rosetta 2（如果需要）
softwareupdate --install-rosetta --agree-to-license

Q3: 环境变量不生效

# 检查是否在正确的配置文件
# macOS Catalina 后默认使用 zsh
cat /etc/shells

# 确保配置文件语法正确
zsh -n ~/.zshrc

Q4: SDK 下载慢

配置镜像源：

# 在 DevEco Studio 设置中配置华为镜像
https://repo.huaweicloud.com/harmonyos

Q5: 模拟器无法启动

# 检查虚拟化是否开启
sysctl -a | grep machdep.cpu.features | grep VMX

# 清理模拟器缓存
rm -rf ~/Library/Huawei/Sdk/emulator/cache

进阶配置

配置别名（可选）

在** ~/.zshrc 或 **~/.bash_profile 中添加：

# DevEco Studio 快捷启动
alias deveco="open -a 'DevEco Studio'"

# HDC 常用命令别名
alias hdc-devices="hdc list targets"
alias hdc-install="hdc app install"
alias hdc-log="hdc shell hilog"

# 快速进入项目目录
alias harm-proj="cd ~/HarmonyProjects"

配置代理（如需要）

# HTTP 代理
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890

# Git 代理（用于下载依赖）
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890

更新维护

更新 DevEco Studio

# 检查更新
# DevEco Studio > Check for Updates

# 或手动下载最新版本替换

更新 SDK

# 通过 SDK Manager 更新
# DevEco Studio > Preferences > HarmonyOS SDK > Check Now

清理旧版本

# 清理旧的 SDK 版本
rm -rf ~/Library/Huawei/Sdk/HarmonyOS-[旧版本]

# 清理缓存
rm -rf ~/Library/Caches/Huawei/DevEcoStudio*

相关资源

• HarmonyOS 官方文档
• DevEco Studio 使用指南
• HarmonyOS 示例代码
• 开发者社区

---

最后更新时间：2024年12月 适用版本：DevEco Studio 4.0+, HarmonyOS SDK API 9+

# Xcode 用户数据
**/xcuserdata/
*.xcodeproj/xcuserdata/
*.xcworkspace/xcuserdata/

# Xcode 构建文件
build/
DerivedData/

# CocoaPods - 只忽略 Pods 目录，不忽略 Podfile 和 Podfile.lock
Pods/

# macOS
.DS_Store

# 其他
*.swp
*~

提交代码时

git add Podfile Podfile.lock .gitignore
git commit -m "Update dependencies"
git push

执行 pod install 后，.xcodeproj 文件被修改了，产生了待提交的内容。

原因分析

当你运行 pod install 时，CocoaPods 会：

1. ✅ 在 Pods/ 目录下载依赖库（已被 .gitignore 忽略）
2. ⚠️ 修改 .xcodeproj/project.pbxproj 文件，添加对 Pods 的引用

首次克隆项目后

# 1. 克隆项目
git clone <your-repo-url>
cd 项目目录

# 2. 安装依赖
pod install

# 3. 提交 .xcodeproj 的修改（如果有）
git add eWordMedical.xcodeproj/project.pbxproj
git commit -m "Update project configuration after pod install"
git push

为什么会有这些修改？ 可能的原因：

1. 路径差异：不同电脑上的绝对路径不同
2. CocoaPods 版本：不同版本的 CocoaPods 生成的配置略有差异
3. 首次安装：如果项目之前没有正确提交 .xcodeproj

这样做的好处：

• 保持项目文件与实际配置一致
• 团队其他成员拉取后可以直接编译

预防措施 为了减少这种情况，团队应该 统一 CocoaPods 版本

# 查看当前版本
pod --version

# 在 Gemfile 中锁定版本（可选）
gem 'cocoapods', '~> 1.15'

确保 .xcworkspace 也被提交

# .xcworkspace 应该提交（包含工作区配置）
git add xxxx.xcworkspace

在 .gitignore 中只忽略用户数据

# 只忽略用户数据，不忽略项目文件
**/xcuserdata/
*.xcworkspace/xcuserdata/

⚠️ 可能冲突的情况

只有在以下情况会冲突：

1. 同时修改项目结构

   • 你：添加了新文件 A
   • 同事：添加了新文件 B
   • 两个人都修改了 .xcodeproj
   • 结果：Git 合并冲突 ❌

2. 同时更新依赖

   • 你：更新了 Alamofire 版本
   • 同事：更新了 SnapKit 版本
   • 两个人都修改了 Podfile.lock 和 .xcodeproj
   • 结果：需要手动合并 ⚠️

CocoaPods 库中的代码有报错问题每次我都需要手动修改为了防止每次都修改以下修改 使用 Podfile 的 post_install 钩子自动修复

post_install do |installer|
  installer.pods_project.targets.each do |target|
    if target.name == 'CountdownLabel'  # 替换为你的 Pod 名称
      target.build_configurations.each do |config|
        # 自动修复感叹号问题
        Dir.glob("Pods/CountdownLabel/**/*.swift").each do |file|
          contents = File.read(file)
          # 将 as !TimeZone 替换为 as? TimeZone
          new_contents = contents.gsub(/as !TimeZone/, 'as? TimeZone')
          File.write(file, new_contents) if contents != new_contents
        end
      end
    end
  end
end