📖 欢迎

欢迎使用 Termony！这是一份专为新手设计的 macOS 环境配置指南，将帮助你从零开始配置开发环境，让 Termony 在你的 Mac 上能够顺利为OpenHarmony适配各种开源命令行工具。

🎯 适用对象

  • ✅ 初次接触OpenHarmony开发的开发者
  • ✅ 需要在 macOS 上配置 Termony 开发环境的用户
  • ✅ 遇到环境配置问题的开发者
  • ✅ 对命令行不太熟悉的新手用户

⏱️ 预计时间

  • 环境配置：15-30 分钟（取决于网络速度）
  • 完整流程：1-2 小时（包括构建和部署）

📚 如何使用本指南

  1. 如果你是新手：建议按照顺序阅读，不要跳过任何步骤
  2. 如果你有经验：可以直接查看"快速开始"章节
  3. 如果遇到问题：查看"常见问题与故障排除"章节
  4. 如果需要帮助：查看"获取帮助"章节

🔑 重要提示

  • ⚠️ 请按照顺序执行：每个步骤都有依赖关系，跳过可能导致后续步骤失败
  • 💡 遇到问题不要慌：大部分问题都有解决方案，查看故障排除章节
  • 📝 建议做笔记：记录你的配置路径和遇到的问题，方便后续参考

📑 目录

  1. 前置条件检查 - 检查你的 Mac 是否满足要求
  2. 快速开始（推荐） - 快速配置环境（适合有经验的用户）
  3. 详细配置步骤 - 详细的配置说明（适合新手）
  4. Java Runtime 环境检测与安装 ⚠️ 签名工具必需
  5. 验证安装 - 验证所有工具是否正确安装
  6. 常见问题与故障排除 - 遇到问题？看这里
  7. 检查清单 - 配置完成后的检查清单
  8. 术语表 - 专业术语解释
  9. 快速参考 - 常用命令速查表
  10. 获取帮助 - 需要帮助？看这里

📋 前置条件检查

在开始配置之前，请确保你的 Mac 满足以下条件。不要跳过这一步，否则可能导致后续配置失败。

💻 系统要求

项目 要求 如何检查
操作系统 macOS 10.15 或更高版本 点击左上角苹果图标 → 关于本机
架构 Apple Silicon (M1/M2/M3) 或 Intel 关于本机中查看"芯片"或"处理器"
磁盘空间 至少 5GB 可用空间 点击苹果图标 → 关于本机 → 存储空间

检查方法：

# 检查 macOS 版本
sw_vers

image-20251115184644699

# 检查架构（Apple Silicon 显示 arm64，Intel 显示 x86_64）
uname -m

image-20251115184802401

# 检查磁盘空间（查看可用空间）
df -h /

image-20251115184928626

📦 必需软件

1. Homebrew（包管理器）

什么是 Homebrew？

Homebrew 是 macOS 上最流行的包管理器，类似于 Windows 的"应用商店"或 Linux 的 apt/yum。它可以帮你轻松安装和管理各种开发工具，而不需要手动下载和配置。

为什么需要 Homebrew？

Termony 项目需要很多开发工具（如 cmake、make 等），使用 Homebrew 可以一键安装这些工具，比手动安装方便得多。

检查是否已安装：

打开终端（Terminal.app），输入以下命令：

brew --version

image-20251115185011220

如果显示版本号（如 Homebrew 5.0.1）：

  • ✅ 说明已安装，可以跳过安装步骤
  • 继续下一步：安装开发工具

如果显示 “command not found”：

  • ❌ 说明未安装，需要先安装 Homebrew

安装 Homebrew：

  1. 打开终端（Terminal.app）

    • 可以在"应用程序" → "实用工具"中找到
    • 或者按 ⌘ + 空格，输入"终端"搜索

  2. 复制并粘贴以下命令：

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  3. 按回车执行，然后：

    • 输入你的 Mac 密码（输入时不会显示，这是正常的）
    • 按回车确认
    • 等待安装完成（可能需要 5-10 分钟，取决于网络速度）

  4. 安装后配置 PATH（重要！）：

    Apple Silicon Mac (M1/M2/M3)：

    echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
eval "$(/opt/homebrew/bin/brew shellenv)"

    Intel Mac：

    echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zshrc
eval "$(/usr/local/bin/brew shellenv)"

    说明：这些命令会将 Homebrew 添加到系统路径中，让系统能找到 Homebrew 安装的工具。

  5. 验证安装：

    brew --version

    预期输出：

    Homebrew 5.0.1
Homebrew/homebrew-core (git revision xxxxx; last commit xxxxx)

    ✅ 如果看到版本号，说明安装成功！

说明：

可执行brew update进行升级。

image-20251117145457078

2. 检查 Shell 类型

什么是 Shell？

Shell 是终端中用来执行命令的程序。macOS 默认使用 zsh，本指南的所有命令都基于 zsh。

检查当前 Shell：

echo $SHELL

预期输出：

  • ✅ /bin/zsh - 正确，可以继续
  • ❌ /bin/bash - 需要切换（见下方）

如果不是 zsh，切换方法：

chsh -s /bin/zsh

切换后需要重新打开终端才能生效。

🚀 快速开始（推荐）

💡 适合对象：对命令行比较熟悉，希望快速配置环境的用户

⚠️ 新手建议：如果你是第一次配置，建议查看"详细配置步骤"章节，那里有更详细的说明

如果你希望快速配置环境，可以按照以下步骤操作：

步骤 1：安装 Homebrew（如果未安装）

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装后配置 PATH（Apple Silicon Mac）：

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
eval "$(/opt/homebrew/bin/brew shellenv)"

步骤 2：批量安装开发工具

brew install --formula wget coreutils make gsed gettext automake cmake pkg-config ncurses

说明：

  • --formula 参数可以避免某些包的冲突问题
  • 安装过程可能需要 10-20 分钟，请耐心等待
  • 如果某个工具安装失败，查看"常见问题"章节

步骤 3：配置 GNU 工具优先级

# 将 GNU 工具路径添加到 PATH 前面
echo 'export PATH="/opt/homebrew/opt/coreutils/libexec/gnubin:/opt/homebrew/opt/gnu-sed/libexec/gnubin:/opt/homebrew/opt/make/libexec/gnubin:$PATH"' >> ~/.zshrc

# 使配置立即生效
source ~/.zshrc

为什么需要这一步？ macOS 自带的工具是 BSD 版本，而构建脚本需要 GNU 版本。这一步确保系统优先使用 GNU 版本。

步骤 4：验证安装

#!/bin/bash
# 开发工具安装验证脚本
# 用于检查必需开发工具是否已正确安装

echo "=== 开发工具安装验证 ==="
echo ""

# 定义要检查的工具列表
tools=("wget" "make" "gsed" "gettext" "automake" "cmake" "pkg-config")

# 检查每个工具
for tool in "${tools[@]}"; do
    if command -v $tool &> /dev/null; then
        # 获取版本信息（取第一行）
        version=$($tool --version 2>&1 | head -1)
        echo "✓ $tool: $version"
    else
        echo "✗ $tool: 未安装"
    fi
done

# 检查 coreutils（特殊处理）
echo ""
echo "=== 检查 coreutils ==="
if brew list coreutils &> /dev/null; then
    cp_path=$(which cp 2>/dev/null)
    if [[ $cp_path == *"/opt/homebrew/bin"* ]] || [[ $cp_path == *"/usr/local/bin"* ]]; then
        echo "✓ coreutils: GNU 版本已安装 ($cp_path)"
    else
        echo "✓ coreutils: 已安装（通过 Homebrew），但 PATH 中可能优先使用系统版本"
        echo "  提示：可以通过 'gcp', 'gls' 等命令使用 GNU 版本"
    fi
else
    echo "✗ coreutils: 未安装"
fi

# 检查 ncurses（库文件，没有可执行文件）
echo ""
echo "=== 检查 ncurses ==="
if brew list ncurses &> /dev/null; then
    # 检查库文件是否存在
    if [ -f "/opt/homebrew/lib/libncurses.dylib" ] || [ -f "/opt/homebrew/lib/libncurses.a" ] || \
       [ -f "/usr/local/lib/libncurses.dylib" ] || [ -f "/usr/local/lib/libncurses.a" ]; then
        echo "✓ ncurses: 库文件已安装"
    else
        echo "✓ ncurses: 已安装（通过 Homebrew）"
    fi
else
    echo "✗ ncurses: 未安装"
fi

echo ""
echo "=== 检查 GNU 工具优先级配置 ==="
# 检查 sed
sed_path=$(which sed 2>/dev/null)
if [[ $sed_path == *"/opt/homebrew/opt/gnu-sed/libexec/gnubin"* ]]; then
    echo "✓ sed: 使用 GNU 版本 ($sed_path)"
else
    echo "⚠ sed: 使用系统版本 ($sed_path)，建议配置 GNU 版本优先级"
fi

# 检查 make
make_path=$(which make 2>/dev/null)
if [[ $make_path == *"/opt/homebrew/opt/make/libexec/gnubin"* ]]; then
    echo "✓ make: 使用 GNU 版本 ($make_path)"
else
    echo "⚠ make: 使用系统版本 ($make_path)，建议配置 GNU 版本优先级"
fi

# 检查 coreutils (cp)
cp_path=$(which cp 2>/dev/null)
if [[ $cp_path == *"/opt/homebrew/opt/coreutils/libexec/gnubin"* ]]; then
    echo "✓ cp: 使用 GNU 版本 ($cp_path)"
else
    echo "⚠ cp: 使用系统版本 ($cp_path)，建议配置 GNU 版本优先级"
fi

echo ""
echo "=== 验证完成 ==="
echo ""
echo "如果发现未安装的工具，请运行："
echo "brew install --formula wget coreutils make gsed gettext automake cmake pkg-config ncurses"
echo ""
echo "如果需要配置 GNU 工具优先级，请运行："
echo 'echo '\''export PATH="/opt/homebrew/opt/coreutils/libexec/gnubin:/opt/homebrew/opt/gnu-sed/libexec/gnubin:/opt/homebrew/opt/make/libexec/gnubin:$PATH"'\'' >> ~/.zshrc'
echo "source ~/.zshrc"

# 运行项目提供的验证脚本（推荐）
./verify-tools.sh

# 或者手动验证
cmake --version
make --version

image-20251116190946856

预期结果：

  • ✅ 所有工具都显示版本号 → 配置成功！
  • ❌ 某些工具显示 “command not found” → 查看"常见问题"章节

完成！ 如果所有工具都显示已安装，说明环境配置成功。接下来可以继续：

  1. 安装 Java Runtime（见"Java Runtime 环境检测与安装"章节）
  2. 配置应用签名（见"应用签名配置实战"章节）
  3. 构建 HNP 包（见"HNP 包构建实战"章节）

📖 详细配置步骤

💡 适合对象：新手用户，希望了解每个步骤的详细说明

📝 提示：如果你已经通过"快速开始"完成了配置，可以跳过这一章节

如果你希望了解每个步骤的详细说明，或者遇到了问题，可以按照以下详细步骤操作。建议按照顺序阅读，不要跳过任何步骤。

第一步：安装 Homebrew

🤔 什么是 Homebrew？

Homebrew 是 macOS 的包管理器，类似于：

  • Windows 的"Microsoft Store"或"Chocolatey"
  • Linux 的 apt（Ubuntu）或 yum（CentOS）
  • Android 的"Google Play Store"

简单来说：Homebrew 可以帮你一键安装各种开发工具，而不需要：

  • ❌ 手动下载安装包
  • ❌ 手动配置环境变量
  • ❌ 手动处理依赖关系
📝 安装步骤

步骤 1：打开终端

  1. 点击 Dock 中的"终端"图标，或
  2. 按 ⌘ + 空格，输入"终端"，按回车，或
  3. 打开"应用程序" → “实用工具” → “终端”

步骤 2：运行安装命令

复制以下命令，粘贴到终端中，按回车：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

步骤 3：按照提示操作

安装过程中会提示你：

  1. 输入密码：

    Password:
    • 输入你的 Mac 登录密码（输入时不会显示，这是正常的）
    • 按回车确认

  2. 确认安装：

    Press RETURN to continue or any other key to abort
    • 按回车继续，或按其他键取消

  3. 等待安装完成：

    • 可能需要 5-10 分钟（取决于网络速度）
    • 看到 Installation successful! 表示安装成功

步骤 4：配置 PATH

安装完成后，需要配置环境变量，让系统能找到 Homebrew 安装的工具。

Apple Silicon Mac (M1/M2/M3)：

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
eval "$(/opt/homebrew/bin/brew shellenv)"

Intel Mac：

echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zshrc
eval "$(/usr/local/bin/brew shellenv)"

说明：

  • echo '...' >> ~/.zshrc：将配置添加到 shell 配置文件
  • eval "$(...)"：立即应用配置（不需要重启终端）

步骤 5：验证安装

brew --version

预期输出：

Homebrew 5.0.1
Homebrew/homebrew-core (git revision xxxxx; last commit xxxxx)

✅ 如果看到版本号，说明安装成功！

❓ 常见问题

Q1: 安装时提示权限错误

错误信息：

Error: Permission denied

解决方案：

  • 确保使用管理员账户（Mac 登录账户）
  • 不要使用 sudo，Homebrew 不需要管理员权限

Q2: 安装速度很慢

原因：Homebrew 需要从 GitHub 下载文件，如果网络较慢会影响速度。

解决方案：

  • 耐心等待（这是正常的）
  • 如果非常慢，可以考虑使用国内镜像源（见"常见问题与故障排除"章节）

Q3: 提示 “command not found: brew”

原因：PATH 环境变量未正确配置。

解决方案：

  1. 重新执行步骤 4 的配置命令
  2. 重新打开终端窗口
  3. 如果还是不行，检查你的 Shell 类型（见前置条件检查）

第二步：安装开发工具

工具列表说明

Termony 需要以下开发工具：

工具 用途 必需性
wget 命令行下载工具 必需
coreutils GNU 核心工具集 必需
make 构建工具 必需
gsed GNU sed（文本处理） 必需
gettext 国际化工具 必需
automake 自动生成 Makefile 必需
cmake 跨平台构建系统 必需
pkg-config 包配置工具 必需
ncurses 终端界面库 必需
安装命令

方法一：批量安装（推荐）

brew install --formula wget coreutils make gsed gettext automake cmake pkg-config ncurses

方法二：逐个安装

如果批量安装遇到问题，可以逐个安装：

brew install --formula wget
brew install --formula coreutils
brew install --formula make
brew install --formula gsed
brew install --formula gettext
brew install --formula automake
brew install --formula cmake
brew install --formula pkg-config
brew install --formula ncurses
可能遇到的问题

问题 1：CMake 安装错误

如果遇到以下错误：

Error: Cask 'cmake' definition is invalid: 'conflicts_with' stanza failed...

解决方案：

# 使用 formula 版本安装
brew install --formula cmake

问题 2：工具已安装但版本不对

# 更新所有工具
brew upgrade wget coreutils make gsed gettext automake cmake pkg-config ncurses

问题 3：网络问题导致下载失败

# 重试安装
brew install --formula <工具名>

# 或者使用国内镜像（见故障排除章节）

第三步：配置 GNU 工具优先级

为什么需要配置？

macOS 自带 BSD 版本的工具（如 sed、make、cp），而 Homebrew 安装的是 GNU 版本。GNU 版本功能更强大、语法更标准，许多构建脚本依赖 GNU 版本。

配置步骤

  1. 确定你的 Shell：

    echo $SHELL
    • 如果显示 /bin/zsh，使用 ~/.zshrc
    • 如果显示 /bin/bash，使用 ~/.bash_profile

  2. 添加环境变量（zsh 用户）：

    echo 'export PATH="/opt/homebrew/opt/coreutils/libexec/gnubin:/opt/homebrew/opt/gnu-sed/libexec/gnubin:/opt/homebrew/opt/make/libexec/gnubin:$PATH"' >> ~/.zshrc

    或者（bash 用户）：

    echo 'export PATH="/opt/homebrew/opt/coreutils/libexec/gnubin:/opt/homebrew/opt/gnu-sed/libexec/gnubin:/opt/homebrew/opt/make/libexec/gnubin:$PATH"' >> ~/.bash_profile

  3. 使配置生效：

    source ~/.zshrc  # zsh 用户
# 或
source ~/.bash_profile  # bash 用户

  4. 验证配置：

    # 检查 sed（应该是 GNU sed）
which sed
sed --version
# 应该显示：sed (GNU sed) 4.9

# 检查 make（应该是 GNU Make）
which make
make --version
# 应该显示：GNU Make 4.4.1

image-20251116191232461

配置说明

路径含义：

  • /opt/homebrew/opt/coreutils/libexec/gnubin：GNU coreutils 工具目录
  • /opt/homebrew/opt/gnu-sed/libexec/gnubin：GNU sed 工具目录
  • /opt/homebrew/opt/make/libexec/gnubin：GNU make 工具目录

配置效果：

  • ✅ 系统优先使用 GNU 版本的工具
  • ✅ 脚本兼容性更好（符合 Linux/GNU 标准）
  • ✅ 功能更强大（支持更多选项）
  • ✅ 避免 BSD/GNU 语法差异导致的问题

注意事项：

  • 配置后，sed、make、cp 等命令会使用 GNU 版本
  • 如果需要使用 BSD 版本，可以使用完整路径（如 /bin/sed）
  • 某些脚本可能依赖 BSD 版本，需要测试兼容性

☕️ Java Runtime 环境检测与安装

为什么需要 Java Runtime？

OpenHarmony 应用的签名工具 hap-sign-tool.jar 需要 Java Runtime Environment (JRE) 来运行。在构建和签名 HAP 包时，sign.py 脚本会调用 Java 来执行签名操作。

检测 Java Runtime

方法一：检查 Java 是否已安装
# 检查 Java 命令是否可用
which java

# 检查 Java 版本
java -version

# 应该看到类似以下输出：
# openjdk version "17.0.2" 2022-01-18
# OpenJDK Runtime Environment (build 17.0.2+8-Ubuntu-120.04)
# OpenJDK 64-Bit Server VM (build 17.0.2+8-Ubuntu-120.04, mixed mode, sharing)
方法二：检查 JAVA_HOME 环境变量
# 检查 JAVA_HOME 是否设置
echo $JAVA_HOME

# 如果设置了，应该显示 Java 安装路径，例如：
# /Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home

安装 Java Runtime

方法一：使用 Homebrew 安装（推荐）

这是最简单的方式，适合 macOS 用户。

步骤 1：安装 OpenJDK

# 安装 OpenJDK（推荐 Java 17 或更高版本）
brew install openjdk@17

# 或者安装最新版本
brew install openjdk

步骤 2：配置环境变量

安装完成后，需要配置环境变量：

# 对于 zsh（macOS 默认）
echo 'export PATH="/opt/homebrew/opt/openjdk@17/bin:$PATH"' >> ~/.zshrc
echo 'export JAVA_HOME="/opt/homebrew/opt/openjdk@17"' >> ~/.zshrc

# 使配置立即生效
source ~/.zshrc

步骤 3：验证安装

# 检查 Java 版本
java -version

# 检查 JAVA_HOME
echo $JAVA_HOME

# 应该看到 Java 版本信息和正确的 JAVA_HOME 路径
方法二：使用 Oracle JDK（官方版本）

如果你需要 Oracle 官方版本：

  1. 访问 Oracle 官网：

    • 打开 https://www.oracle.com/java/technologies/downloads/
    • 选择 macOS 版本
    • 下载 JDK 安装包（.dmg 文件）

  2. 安装 JDK：

    • 双击下载的 .dmg 文件
    • 按照安装向导完成安装

  3. 配置环境变量：

    # 查找 Java 安装路径
/usr/libexec/java_home -V

# 设置 JAVA_HOME（替换为实际路径）
echo 'export JAVA_HOME=$(/usr/libexec/java_home)' >> ~/.zshrc
echo 'export PATH="$JAVA_HOME/bin:$PATH"' >> ~/.zshrc

# 使配置生效
source ~/.zshrc
方法三：使用 Adoptium（Eclipse Temurin）

Adoptium 提供预构建的 OpenJDK 二进制文件：

  1. 访问 Adoptium 官网：

    • 打开 https://adoptium.net/
    • 选择 macOS 和 Java 版本
    • 下载 .pkg 安装包

  2. 安装：

    • 双击 .pkg 文件
    • 按照安装向导完成安装

  3. 配置环境变量：

    # 查找 Java 安装路径
/usr/libexec/java_home -V

# 设置环境变量
echo 'export JAVA_HOME=$(/usr/libexec/java_home)' >> ~/.zshrc
echo 'export PATH="$JAVA_HOME/bin:$PATH"' >> ~/.zshrc

# 使配置生效
source ~/.zshrc

Java 版本要求

OpenHarmony 签名工具通常需要：

  • 最低版本：Java 8 或更高版本
  • 推荐版本：Java 11、Java 17 或 Java 21（LTS 版本）

检查当前 Java 版本：

java -version 2>&1 | head -1
# 应该显示类似：openjdk version "17.0.2"

验证 Java Runtime

完整验证步骤
# 1. 检查 Java 命令
which java
# 应该显示：/opt/homebrew/opt/openjdk@17/bin/java 或类似路径

# 2. 检查 Java 版本
java -version
# 应该显示版本信息

# 3. 检查 JAVA_HOME
echo $JAVA_HOME
# 应该显示 Java 安装目录

# 4. 测试运行 Java 程序
java -version
# 应该能正常输出版本信息

# 5. 检查 Java 编译器（可选，签名不需要）
javac -version
# 如果安装了 JDK，应该显示编译器版本
验证签名工具可用性
# 检查 OpenHarmony 签名工具是否存在
ls -lh /Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains/lib/hap-sign-tool.jar

# 测试运行签名工具（会显示帮助信息）
java -jar /Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains/lib/hap-sign-tool.jar --help

Java Runtime 常见问题

问题 1：找不到 Java 命令

错误信息：

The operation couldn't be completed. Unable to locate a Java Runtime.
Please visit http://www.java.com for information on installing Java.

解决方案：

  1. 使用 Homebrew 安装 Java：brew install openjdk@17
  2. 配置 PATH 环境变量
  3. 重新加载 shell 配置：source ~/.zshrc

问题 2：Java 版本不兼容

错误信息：

Error: A JNI error has occurred, please check your installation

解决方案：

  • 确保使用 Java 8 或更高版本
  • 推荐使用 Java 11、17 或 21（LTS 版本）
  • 检查 JAVA_HOME 是否正确设置

问题 3：JAVA_HOME 未设置

错误信息：

JAVA_HOME is not set

解决方案：

# 查找 Java 安装路径
/usr/libexec/java_home -V

# 设置 JAVA_HOME
echo 'export JAVA_HOME=$(/usr/libexec/java_home)' >> ~/.zshrc
source ~/.zshrc

问题 4：多个 Java 版本冲突

解决方案：

# 查看所有已安装的 Java 版本
/usr/libexec/java_home -V

# 切换到特定版本
export JAVA_HOME=$(/usr/libexec/java_home -v 17)

# 或者使用 jenv 管理多个 Java 版本
brew install jenv

Java Runtime 验证清单

在构建和签名 HAP 包之前，请确认：

  • Java 已安装（java -version 可以正常运行）
  • Java 版本符合要求（Java 8 或更高，推荐 Java 17）
  • JAVA_HOME 环境变量已设置（echo $JAVA_HOME 显示路径）
  • PATH 中包含 Java bin 目录（which java 显示路径）
  • 可以运行 Java 程序（java -version 正常输出）
  • OpenHarmony 签名工具可用（hap-sign-tool.jar 存在）

🧪 验证安装

方法一：使用验证脚本（推荐）

项目根目录提供了验证脚本 verify-tools.sh：

# 运行验证脚本
./verify-tools.sh

脚本会检查：

  • ✅ 所有必需工具的安装状态
  • ✅ 每个工具的版本信息
  • ✅ GNU 工具优先级配置
  • ✅ 提供安装和配置建议

预期输出：

=== 开发工具安装验证 ===

✓ wget: GNU Wget 1.25.0
✓ make: GNU Make 4.4.1
✓ gsed: gsed (GNU sed) 4.9
✓ gettext: gettext (GNU gettext-runtime) 0.25
✓ automake: automake (GNU automake) 1.17
✓ cmake: cmake version 4.0.2
✓ pkg-config: 2.4.3

=== 检查 coreutils ===
✓ coreutils: 已安装（通过 Homebrew）

=== 检查 ncurses ===
✓ ncurses: 已安装（通过 Homebrew）

=== 检查 GNU 工具优先级配置 ===
✓ sed: 使用 GNU 版本
✓ make: 使用 GNU 版本
✓ cp: 使用 GNU 版本

=== 验证完成 ===

方法二：手动验证

如果不想使用脚本，可以手动检查：

# 检查各个工具
wget --version
make --version
cmake --version
pkg-config --version
gettext --version
automake --version
gsed --version

# 检查 GNU 工具优先级
which sed
sed --version  # 应该显示 GNU sed

which make
make --version  # 应该显示 GNU Make

which cp
cp --version  # 应该显示 GNU coreutils

验证清单

请确认以下所有项目都显示 ✓：

  • Homebrew 已安装并可运行
  • wget 已安装
  • coreutils 已安装
  • make 已安装（GNU 版本）
  • gsed 已安装
  • gettext 已安装
  • automake 已安装
  • cmake 已安装
  • pkg-config 已安装
  • ncurses 已安装
  • GNU 工具优先级已配置（sed、make、cp 使用 GNU 版本）
  • Java Runtime 已安装（java -version 可以正常运行）
  • JAVA_HOME 环境变量已设置

🧯 常见问题与故障排除

问题 1：Homebrew 安装 CMake 失败

错误信息：

Error: Cask 'cmake' definition is invalid: 'conflicts_with' stanza failed...

原因：Homebrew 5.0+ 版本禁用了 conflicts_with 功能，但某些 cask 定义还在使用它。

解决方案：

# 使用 formula 版本安装（推荐）
brew install --formula cmake

验证：

cmake --version
# 应该显示：cmake version 4.0.2

问题 2：找不到命令（command not found）

症状：安装工具后，运行命令时提示 “command not found”

可能原因：

  1. PATH 未正确配置
  2. 工具未正确安装
  3. Shell 配置未生效

解决方案：

  1. 检查工具是否安装：

    brew list | grep cmake

  2. 检查 PATH：

    echo $PATH
# 应该包含 /opt/homebrew/bin

  3. 添加 PATH（如果缺失）：

    echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

  4. 检查工具位置：

    which cmake
# 应该显示：/opt/homebrew/bin/cmake

问题 3：GNU 工具优先级未生效

症状：配置了 PATH，但 sed、make 仍使用系统版本

检查方法：

which sed
# 如果显示 /bin/sed，说明使用的是系统版本
# 应该显示 /opt/homebrew/opt/gnu-sed/libexec/gnubin/sed

解决方案：

  1. 确认配置已添加：

    tail -5 ~/.zshrc
# 应该看到 PATH 配置

  2. 重新加载配置：

    source ~/.zshrc

  3. 检查 PATH 顺序：

    echo $PATH | tr ':' '\n' | grep -E "(coreutils|gnu-sed|make)"
# GNU 工具的路径应该在前面

  4. 如果仍未生效，手动设置：

    export PATH="/opt/homebrew/opt/coreutils/libexec/gnubin:/opt/homebrew/opt/gnu-sed/libexec/gnubin:/opt/homebrew/opt/make/libexec/gnubin:$PATH"

问题 4：Homebrew 更新失败

症状：运行 brew update 时失败或很慢

可能原因：

  • 网络连接问题
  • 使用了镜像源但配置不正确
  • Homebrew 仓库损坏

解决方案：

  1. 检查网络连接：

    ping github.com

  2. 切换到官方源（如果使用了镜像）：

    git -C "/opt/homebrew" remote set-url origin https://github.com/Homebrew/brew

  3. 重置更新：

    brew update-reset
brew update

  4. 修复仓库：

    brew tap --repair

问题 5：安装工具时网络超时

症状：下载工具时超时或失败

解决方案：

  1. 重试安装：

    brew install --formula <工具名>

  2. 使用国内镜像（如果在中国）：

    # 设置 Homebrew 镜像（清华大学）
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"
export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git"

# 然后重新安装
brew install --formula <工具名>

  3. 使用代理（如果有）：

    export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
brew install --formula <工具名>

问题 6：磁盘空间不足

症状：安装时提示磁盘空间不足

解决方案：

  1. 清理 Homebrew 缓存：

    brew cleanup

  2. 删除旧版本：

    brew cleanup --prune=all

  3. 检查磁盘空间：

    df -h

问题 7：权限问题

症状：安装或配置时提示权限错误

解决方案：

  1. 检查文件权限：

    ls -la ~/.zshrc

  2. 修复权限：

    chmod 644 ~/.zshrc

  3. 检查 Homebrew 目录权限：

    ls -la /opt/homebrew

✅ 检查清单

在开始使用 Termony 之前，请确认以下所有项目都已完成：

基础环境

  • macOS 10.15 或更高版本
  • 至少 5GB 可用磁盘空间
  • 网络连接正常

Homebrew

  • Homebrew 已安装
  • brew --version 可以正常运行
  • Homebrew 已更新到最新版本（brew update）

开发工具

  • wget 已安装（wget --version）
  • coreutils 已安装（brew list coreutils）
  • make 已安装（make --version）
  • gsed 已安装（gsed --version）
  • gettext 已安装（gettext --version）
  • automake 已安装（automake --version）
  • cmake 已安装（cmake --version）
  • pkg-config 已安装（pkg-config --version）
  • ncurses 已安装（brew list ncurses）

GNU 工具配置

  • PATH 已配置（echo $PATH 包含 GNU 工具路径）
  • sed 使用 GNU 版本（sed --version 显示 GNU sed）
  • make 使用 GNU 版本（make --version 显示 GNU Make）
  • cp 使用 GNU 版本（cp --version 显示 GNU coreutils）

验证

  • 运行 ./verify-tools.sh 所有检查通过
  • 所有工具版本符合要求
  • 没有错误或警告信息

工具详细说明

wget - 命令行下载工具

用途：从网络下载文件，支持 HTTP、HTTPS、FTP 协议

常用命令：

wget https://example.com/file.zip              # 下载文件
wget -c https://example.com/file.zip           # 断点续传
wget -O output.zip https://example.com/file.zip  # 指定输出文件名

验证：

wget --version
# 输出：GNU Wget 1.25.0

coreutils - GNU 核心工具集

用途：提供标准 Unix 命令的 GNU 版本（cp, ls, mv, rm, cat 等）

说明：macOS 自带 BSD 版本，GNU 版本功能更强大、语法更标准

常用命令：

cp file1 file2        # 复制文件（GNU 版本）
ls -lh               # 列出文件（GNU 版本）
mv file1 file2       # 移动文件（GNU 版本）

验证：

cp --version
# 输出：cp (GNU coreutils) 9.7

make - 构建工具

用途：根据 Makefile 执行构建任务

常用命令：

make                    # 执行默认目标
make -C build-hnp       # 在指定目录执行 make
make clean              # 清理构建产物
make -j4                # 并行构建（4 个任务）

验证：

make --version
# 输出：GNU Make 4.4.1

gsed (GNU sed) - 文本处理工具

用途：流式文本编辑器，用于文本替换、删除、插入等操作

常用命令：

sed 's/old/new/g' file.txt              # 替换文本
sed -i 's/old/new/g' file.txt           # 原地修改文件
sed -n '10,20p' file.txt                # 打印第 10-20 行

验证：

sed --version
# 输出：sed (GNU sed) 4.9

BSD vs GNU 差异：

  • BSD sed：sed -i '' 's/old/new/g' file（需要空字符串）
  • GNU sed：sed -i 's/old/new/g' file（不需要空字符串）

gettext - 国际化工具

用途：国际化（i18n）工具集，用于多语言支持

常用命令：

xgettext source.c -o messages.po         # 提取可翻译字符串
msgfmt messages.po -o messages.mo       # 编译翻译文件

验证：

gettext --version
# 输出：gettext (GNU gettext-runtime) 0.25

automake - 自动生成 Makefile

用途：自动生成符合 GNU 标准的 Makefile

说明：通常与 autoconf 一起使用，用于生成构建系统

验证：

automake --version
# 输出：automake (GNU automake) 1.17

cmake - 跨平台构建系统

用途：跨平台构建系统生成器，用于管理 C/C++ 项目构建

常用命令：

cmake .                                  # 在当前目录配置
cmake -B build                           # 在 build 目录配置
cmake --build build                      # 构建项目
cmake --install build                    # 安装

验证：

cmake --version
# 输出：cmake version 4.0.2

在项目中使用：

cmake_minimum_required(VERSION 3.5.0)
project(Termony)

pkg-config - 包配置工具

用途：查找已安装库的编译和链接标志

常用命令：

pkg-config --cflags freetype2            # 获取编译标志
pkg-config --libs freetype2               # 获取链接标志
pkg-config --modversion freetype2         # 获取版本号

验证：

pkg-config --version
# 输出：2.4.3

在 CMake 中使用：

find_package(PkgConfig REQUIRED)
pkg_check_modules(FREETYPE REQUIRED freetype2)

ncurses - 终端界面库

用途：终端界面库，用于创建文本模式的用户界面

说明：这是库文件，没有直接的可执行文件，主要用于编程

验证：

brew list ncurses
# 应该显示已安装的文件列表

在 CMake 中使用：

find_package(Curses REQUIRED)
target_link_libraries(target ${CURSES_LIBRARIES})

📚 术语表

为了方便新手理解，这里解释一些专业术语：

术语 解释 类比
Homebrew macOS 的包管理器，用于安装开发工具 类似 Windows 的应用商店
Shell 终端中用来执行命令的程序（macOS 默认是 zsh） 类似 Windows 的命令提示符
PATH 系统环境变量，告诉系统在哪里查找可执行文件 类似 Windows 的系统路径
HNP OpenHarmony Native Package，OpenHarmony 原生包格式 类似 Android 的 AAR 包
HAP OpenHarmony Application Package，OpenHarmony 应用安装包格式 类似 Android 的 APK
hdc OpenHarmony Device Connector，OpenHarmony 设备连接工具 类似 Android 的 adb
DevEco Studio OpenHarmony 官方开发工具 类似 Android Studio
签名 对应用进行数字签名，确保应用来源可信且未被篡改 类似给文件盖章
GNU 一个自由软件操作系统项目，提供很多标准工具 -
BSD 另一种 Unix 操作系统，macOS 基于 BSD -
终端 命令行界面，用于输入和执行命令 类似 Windows 的命令提示符
环境变量 系统配置信息，程序可以通过它获取配置 类似程序的设置项

🔍 快速参考

常用命令速查表

命令 用途 示例
brew --version 检查 Homebrew 版本 brew --version
brew install <包名> 安装软件包 brew install cmake
java -version 检查 Java 版本 java -version
cmake --version 检查 CMake 版本 cmake --version
make --version 检查 Make 版本 make --version
hdc list targets 列出已连接的设备 hdc list targets
./verify-tools.sh 验证所有工具安装 ./verify-tools.sh
./create-hnp.sh 构建 HNP 包 ./create-hnp.sh
./build-macos.sh 构建 HAP 包 ./build-macos.sh
./push.sh <HAP包> 部署 HAP 包到设备 ./push.sh entry-default-signed.hap

重要文件路径

文件/目录 路径 说明
Homebrew 安装目录（Apple Silicon） /opt/homebrew Homebrew 主目录
Homebrew 安装目录（Intel） /usr/local Homebrew 主目录
Shell 配置文件 ~/.zshrc zsh 的配置文件
HNP 包 build-hnp/base.hnp 构建后的 HNP 包
HAP 包（未签名） entry/build/default/outputs/default/entry-default-unsigned.hap 构建后的未签名 HAP 包
HAP 包（已签名） entry/build/default/outputs/default/entry-default-signed.hap 签名后的 HAP 包
签名配置文件 build-profile.json5 应用签名配置

环境变量

变量名 说明 如何设置
PATH 系统查找命令的路径 在 ~/.zshrc 中添加 export PATH=...
JAVA_HOME Java 安装目录 export JAVA_HOME=/path/to/java
TOOL_HOME DevEco Studio 工具目录 export TOOL_HOME=/Applications/DevEco-Studio.app/Contents
OHOS_SDK_HOME OpenHarmony SDK 路径 export OHOS_SDK_HOME=$TOOL_HOME/sdk/default/openharmony

快捷键

快捷键 功能 说明
⌘ + 空格 Spotlight 搜索 快速打开应用或文件
⌘ + ; 项目结构（DevEco Studio） 打开项目配置
Ctrl + C 取消当前命令 中断正在执行的命令
Ctrl + D 退出终端 关闭终端窗口

💬 获取帮助

如果遇到问题，可以：

  1. 查看项目文档：

    • docs/ 目录下的文档
    • 项目 README.md 文件

  2. 运行验证脚本：

    ./verify-tools.sh

  3. 检查工具版本：

    <工具名> --version

  4. 搜索问题：

    • 在"常见问题与故障排除"章节查找
    • 使用搜索引擎搜索错误信息

  5. 获取社区帮助：

    • 提交 Issue 到项目仓库
    • 在项目讨论区提问
# harmonyos # 开源
Logo
人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

Qt 与开源鸿蒙融合：构建全场景原生应用新生态

摘要（150字）： Qt作为跨平台C++框架，正加速适配OpenHarmony生态，支持开发者将桌面/移动应用无缝扩展至鸿蒙系统。其核心优势包括原生性能、500+组件库及多语言支持。目前开源鸿蒙版Qt已完成基础框架适配，涵盖QML引擎优化、鸿蒙系统服务集成及开发工具链完善。社区同步启动征文活动，聚焦框架融合、性能优化等方向，鼓励开发者分享迁移经验。参与需提交至GitCode代码仓及技术平台。通过开

avatar 人工智能6S服务平台

Qt-for-鸿蒙PC-Electron应用鸿蒙平台白屏问题修复实战

本文针对Electron应用在鸿蒙平台运行时出现白屏，窗口正常打开但内容空白的问题，进行了详细的解决方案的描述，最终有效解决了鸿蒙平台白屏问题，同时提供了更完善的错误提示和调试支持。

avatar 人工智能6S服务平台
cover

开源鸿蒙终端工具Termony构建HNP包指导手册Mac版

avatar 人工智能6S服务平台