📖 欢迎
欢迎使用 Termony！这是一份专为新手设计的 macOS 环境配置指南，将帮助你从零开始配置开发环境，让 Termony 在你的 Mac 上能够顺利为 OpenHarmony 适配各种开源命令行工具。
🎯 适用对象
⏱️ 预计时间
环境配置：15-30 分钟（取决于网络速度）
完整流程：1-2 小时（包括构建和部署）
📚 如何使用本指南
如果你是新手：建议按照顺序阅读，不要跳过任何步骤
如果你有经验：可以直接查看"快速开始"章节
如果遇到问题：查看"常见问题与故障排除"章节
如果需要帮助：查看"获取帮助"章节
🔑 重要提示
⚠️ 请按照顺序执行：每个步骤都有依赖关系，跳过可能导致后续步骤失败
💡 遇到问题不要慌：大部分问题都有解决方案，查看故障排除章节
📝 建议做笔记：记录你的配置路径和遇到的问题，方便后续参考
📑 目录
前置条件检查 - 检查你的 Mac 是否满足要求
快速开始（推荐） - 快速配置环境（适合有经验的用户）
详细配置步骤 - 详细的配置说明（适合新手）
Java Runtime 环境检测与安装 ⚠️ 签名工具必需
验证安装 - 验证所有工具是否正确安装
常见问题与故障排除 - 遇到问题？看这里
检查清单 - 配置完成后的检查清单
术语表 - 专业术语解释
快速参考 - 常用命令速查表
获取帮助 - 需要帮助？看这里
📋 前置条件检查
在开始配置之前，请确保你的 Mac 满足以下条件。不要跳过这一步，否则可能导致后续配置失败。
💻 系统要求
检查方法：
# 检查架构（Apple Silicon 显示 arm64，Intel 显示 x86_64）uname -m
复制代码
📦 必需软件
1. Homebrew（包管理器）
什么是 Homebrew？
Homebrew 是 macOS 上最流行的包管理器，类似于 Windows 的"应用商店"或 Linux 的 apt/yum。它可以帮你轻松安装和管理各种开发工具，而不需要手动下载和配置。
为什么需要 Homebrew？
Termony 项目需要很多开发工具（如 cmake、make 等），使用 Homebrew 可以一键安装这些工具，比手动安装方便得多。
检查是否已安装：
打开终端（Terminal.app），输入以下命令：
如果显示版本号（如 Homebrew 5.0.1）：
✅ 说明已安装，可以跳过安装步骤
继续下一步：安装开发工具
如果显示 "command not found"：
安装 Homebrew：
打开终端（Terminal.app）
可以在"应用程序" → "实用工具"中找到
或者按 ⌘ + 空格，输入"终端"搜索
复制并粘贴以下命令：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
复制代码
按回车执行，然后：
输入你的 Mac 密码（输入时不会显示，这是正常的）
按回车确认
等待安装完成（可能需要 5-10 分钟，取决于网络速度）
安装后配置 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 安装的工具。
验证安装：
预期输出：
Homebrew 5.0.1 Homebrew/homebrew-core (git revision xxxxx; last commit xxxxx)
复制代码
✅ 如果看到版本号，说明安装成功！
说明：
可执行brew update进行升级。
2. 检查 Shell 类型
什么是 Shell？
Shell 是终端中用来执行命令的程序。macOS 默认使用 zsh，本指南的所有命令都基于 zsh。
检查当前 Shell：
预期输出：
✅ /bin/zsh - 正确，可以继续
❌ /bin/bash - 需要切换（见下方）
如果不是 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)"' >> ~/.zshrceval "$(/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: 未安装" fidone
# 检查 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 版本" fielse 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）" fielse echo "✗ ncurses: 未安装"fi
echo ""echo "=== 检查 GNU 工具优先级配置 ==="# 检查 sedsed_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
# 检查 makemake_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 --versionmake --version
复制代码
预期结果：
完成！ 如果所有工具都显示已安装，说明环境配置成功。接下来可以继续：
安装 Java Runtime（见"Java Runtime 环境检测与安装"章节）
配置应用签名（见"应用签名配置实战"章节）
构建 HNP 包（见"HNP 包构建实战"章节）
📖 详细配置步骤
💡 适合对象：新手用户，希望了解每个步骤的详细说明
📝 提示：如果你已经通过"快速开始"完成了配置，可以跳过这一章节
如果你希望了解每个步骤的详细说明，或者遇到了问题，可以按照以下详细步骤操作。建议按照顺序阅读，不要跳过任何步骤。
第一步：安装 Homebrew
🤔 什么是 Homebrew？
Homebrew 是 macOS 的包管理器，类似于：
Windows 的"Microsoft Store"或"Chocolatey"
Linux 的 apt（Ubuntu）或 yum（CentOS）
Android 的"Google Play Store"
简单来说：Homebrew 可以帮你一键安装各种开发工具，而不需要：
❌ 手动下载安装包
❌ 手动配置环境变量
❌ 手动处理依赖关系
📝 安装步骤
步骤 1：打开终端
点击 Dock 中的"终端"图标，或
按 ⌘ + 空格，输入"终端"，按回车，或
打开"应用程序" → "实用工具" → "终端"
步骤 2：运行安装命令
复制以下命令，粘贴到终端中，按回车：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
复制代码
步骤 3：按照提示操作
安装过程中会提示你：
输入密码：
确认安装：
Press RETURN to continue or any other key to abort
复制代码
等待安装完成：
可能需要 5-10 分钟（取决于网络速度）
看到 Installation successful! 表示安装成功
步骤 4：配置 PATH
安装完成后，需要配置环境变量，让系统能找到 Homebrew 安装的工具。
Apple Silicon Mac (M1/M2/M3)：
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrceval "$(/opt/homebrew/bin/brew shellenv)"
复制代码
Intel Mac：
echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zshrceval "$(/usr/local/bin/brew shellenv)"
复制代码
说明：
步骤 5：验证安装
预期输出：
Homebrew 5.0.1Homebrew/homebrew-core (git revision xxxxx; last commit xxxxx)
复制代码
✅ 如果看到版本号，说明安装成功！
❓ 常见问题
Q1: 安装时提示权限错误
错误信息：
解决方案：
Q2: 安装速度很慢
原因：Homebrew 需要从 GitHub 下载文件，如果网络较慢会影响速度。
解决方案：
Q3: 提示 "command not found: brew"
原因：PATH 环境变量未正确配置。
解决方案：
重新执行步骤 4 的配置命令
重新打开终端窗口
如果还是不行，检查你的 Shell 类型（见前置条件检查）
第二步：安装开发工具
工具列表说明
Termony 需要以下开发工具：
安装命令
方法一：批量安装（推荐）
brew install --formula wget coreutils make gsed gettext automake cmake pkg-config ncurses
复制代码
方法二：逐个安装
如果批量安装遇到问题，可以逐个安装：
brew install --formula wgetbrew install --formula coreutilsbrew install --formula makebrew install --formula gsedbrew install --formula gettextbrew install --formula automakebrew install --formula cmakebrew install --formula pkg-configbrew 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 版本。
配置步骤
确定你的 Shell：
添加环境变量（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
复制代码
使配置生效：
source ~/.zshrc # zsh 用户 # 或 source ~/.bash_profile # bash 用户
复制代码
验证配置：
# 检查 sed（应该是 GNU sed） which sed sed --version # 应该显示：sed (GNU sed) 4.9 # 检查 make（应该是 GNU Make） which make make --version # 应该显示：GNU Make 4.4.1
复制代码
配置说明
路径含义：
/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 工具目录
配置效果：
注意事项：
☕️ 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"' >> ~/.zshrcecho 'export JAVA_HOME="/opt/homebrew/opt/openjdk@17"' >> ~/.zshrc
# 使配置立即生效source ~/.zshrc
复制代码
步骤 3：验证安装
# 检查 Java 版本java -version
# 检查 JAVA_HOMEecho $JAVA_HOME
# 应该看到 Java 版本信息和正确的 JAVA_HOME 路径
复制代码
方法二：使用 Oracle JDK（官方版本）
如果你需要 Oracle 官方版本：
访问 Oracle 官网：
打开 https://www.oracle.com/java/technologies/downloads/
选择 macOS 版本
下载 JDK 安装包（.dmg 文件）
安装 JDK：
双击下载的 .dmg 文件
按照安装向导完成安装
配置环境变量：
# 查找 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 二进制文件：
访问 Adoptium 官网：
打开 https://adoptium.net/
选择 macOS 和 Java 版本
下载 .pkg 安装包
安装：
双击 .pkg 文件
按照安装向导完成安装
配置环境变量：
# 查找 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 版本：
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_HOMEecho $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.
复制代码
解决方案：
使用 Homebrew 安装 Java：brew install openjdk@17
配置 PATH 环境变量
重新加载 shell 配置：source ~/.zshrc
问题 2：Java 版本不兼容
错误信息：
Error: A JNI error has occurred, please check your installation
复制代码
解决方案：
问题 3：JAVA_HOME 未设置
错误信息：
解决方案：
# 查找 Java 安装路径/usr/libexec/java_home -V
# 设置 JAVA_HOMEecho 'export JAVA_HOME=$(/usr/libexec/java_home)' >> ~/.zshrcsource ~/.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 --versionmake --versioncmake --versionpkg-config --versiongettext --versionautomake --versiongsed --version
# 检查 GNU 工具优先级which sedsed --version # 应该显示 GNU sed
which makemake --version # 应该显示 GNU Make
which cpcp --version # 应该显示 GNU coreutils
复制代码
验证清单
请确认以下所有项目都显示 ✓：
🧯 常见问题与故障排除
问题 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"
可能原因：
PATH 未正确配置
工具未正确安装
Shell 配置未生效
解决方案：
检查工具是否安装：
检查 PATH：
echo $PATH # 应该包含 /opt/homebrew/bin
复制代码
添加 PATH（如果缺失）：
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc source ~/.zshrc
复制代码
检查工具位置：
which cmake # 应该显示：/opt/homebrew/bin/cmake
复制代码
问题 3：GNU 工具优先级未生效
症状：配置了 PATH，但 sed、make 仍使用系统版本
检查方法：
which sed# 如果显示 /bin/sed，说明使用的是系统版本# 应该显示 /opt/homebrew/opt/gnu-sed/libexec/gnubin/sed
复制代码
解决方案：
确认配置已添加：
tail -5 ~/.zshrc # 应该看到 PATH 配置
复制代码
重新加载配置：
检查 PATH 顺序：
echo $PATH | tr ':' '\n' | grep -E "(coreutils|gnu-sed|make)" # GNU 工具的路径应该在前面
复制代码
如果仍未生效，手动设置：
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 仓库损坏
解决方案：
检查网络连接：
切换到官方源（如果使用了镜像）：
git -C "/opt/homebrew" remote set-url origin https://github.com/Homebrew/brew
复制代码
重置更新：
brew update-reset brew update
复制代码
修复仓库：
问题 5：安装工具时网络超时
症状：下载工具时超时或失败
解决方案：
重试安装：
brew install --formula <工具名>
复制代码
使用国内镜像（如果在中国）：
# 设置 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 <工具名>
复制代码
使用代理（如果有）：
export http_proxy=http://127.0.0.1:7890 export https_proxy=http://127.0.0.1:7890 brew install --formula <工具名>
复制代码
问题 6：磁盘空间不足
症状：安装时提示磁盘空间不足
解决方案：
清理 Homebrew 缓存：
删除旧版本：
检查磁盘空间：
问题 7：权限问题
症状：安装或配置时提示权限错误
解决方案：
检查文件权限：
修复权限：
检查 Homebrew 目录权限：
✅ 检查清单
在开始使用 Termony 之前，请确认以下所有项目都已完成：
基础环境
[ ] macOS 10.15 或更高版本
[ ] 至少 5GB 可用磁盘空间
[ ] 网络连接正常
Homebrew
开发工具
[ ] 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）
验证
工具详细说明
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 # 在指定目录执行 makemake 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 差异：
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})
复制代码
📚 术语表
为了方便新手理解，这里解释一些专业术语：
🔍 快速参考
常用命令速查表
重要文件路径
环境变量
快捷键
💬 获取帮助
如果遇到问题，可以：
查看项目文档：
docs/ 目录下的文档
项目 README.md 文件
运行验证脚本：
检查工具版本：
搜索问题：
在"常见问题与故障排除"章节查找
使用搜索引擎搜索错误信息
获取社区帮助：
提交 Issue 到项目仓库
在项目讨论区提问
评论