3. Linux 开发环境准备（一）：安装 Ubuntu 虚拟机

做 HarmonyOS 设备开发，绕不开 Linux 环境。我见过不少新手在 Windows 上硬磕编译，最后被各种路径错误和依赖冲突搞得心态崩溃。说白了，官方推荐的 Ubuntu 环境就是最省心的选择。这一章，我带你把虚拟机搭起来，把源配好，把基础工具链装齐。

3.1 为什么非要用虚拟机？

你可能会问：我直接装双系统不行吗？当然可以。但我个人习惯用虚拟机，原因很简单——快照。编译环境搞坏了，点一下恢复，比重装系统快太多了。

3.2 安装 Ubuntu 虚拟机（VMware 为例）

我以 VMware Workstation Pro 17 为例。VirtualBox 流程类似，只是界面稍有不同。嗯，这里要注意：虚拟机版本选 Ubuntu 20.04 LTS 或 22.04 LTS，别追新，LTS 版本最稳。

3.2.1 创建虚拟机

1. 打开 VMware，点击「创建新的虚拟机」。
2. 选择「典型（推荐）」→「稍后安装操作系统」。
3. 客户机操作系统选「Linux」，版本选「Ubuntu 64 位」。
4. 虚拟机名称填 HarmonyOS_Dev，位置选个剩余空间大于 80GB 的盘。
5. 磁盘大小给 80GB（实际编译产物会占 30-50GB），选择「将虚拟磁盘存储为单个文件」。
6. 点击「自定义硬件」→ 内存给 8GB（最低 4GB），处理器给 4 核。

3.2.2 安装 Ubuntu 系统

1. 下载 Ubuntu 20.04 LTS 的 ISO 镜像（清华源或阿里源都行）。
2. 在虚拟机设置中挂载 ISO 文件，启动虚拟机。
3. 安装过程中语言选 English（终端操作避免中文编码问题）。
4. 分区选「Erase disk and install Ubuntu」即可，不用手动分区。
5. 创建用户时，用户名建议全小写英文，不要用中文。

3.3 配置国内软件源

Ubuntu 默认的源在国外，下载速度慢得让人抓狂。我当年第一次编译时，光 apt update 就等了半小时。换成国内源后，速度直接起飞。

3.3.1 备份原源文件

sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak

3.3.2 替换为清华源（Ubuntu 20.04）

sudo sed -i 's@http://archive.ubuntu.com/ubuntu@https://mirrors.tuna.tsinghua.edu.cn/ubuntu@g' /etc/apt/sources.list
sudo sed -i 's@http://security.ubuntu.com/ubuntu@https://mirrors.tuna.tsinghua.edu.cn/ubuntu@g' /etc/apt/sources.list

如果你是 Ubuntu 22.04，把上面的 focal 换成 jammy 就行。或者直接手动编辑文件，把内容替换成下面这样：

deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ focal main restricted universe multiverse
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ focal-updates main restricted universe multiverse
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ focal-backports main restricted universe multiverse
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ focal-security main restricted universe multiverse

3.3.3 更新软件包索引

sudo apt update
sudo apt upgrade -y

3.4 安装必要的依赖包

HarmonyOS 设备开发需要一套完整的工具链。我整理了一份清单，你直接复制粘贴执行就行。

3.4.1 基础编译工具

sudo apt install -y python3 python3-pip python3-venv
sudo apt install -y git git-lfs
sudo apt install -y gcc g++ gdb
sudo apt install -y make cmake ninja-build
sudo apt install -y curl wget unzip tar
sudo apt install -y openssl libssl-dev
sudo apt install -y libncurses5-dev libncursesw5-dev

3.4.2 配置 Python 环境

HarmonyOS 的编译脚本依赖 Python 3.8+。我个人习惯用 venv 隔离环境，避免和系统 Python 打架。

# 创建虚拟环境
python3 -m venv ~/harmony_venv

# 激活环境
source ~/harmony_venv/bin/activate

# 升级 pip
pip install --upgrade pip

# 安装常用 Python 包
pip install setuptools wheel
pip install pyyaml requests

3.4.3 验证安装

装完后，跑一遍验证命令，确保每个工具都能正常调用：

python3 --version   # 应输出 Python 3.8.x 或 3.10.x
git --version       # 应输出 git 2.25.x 以上
gcc --version       # 应输出 gcc 9.x 或 11.x
cmake --version     # 应输出 cmake 3.16.x 以上
make --version      # 应输出 GNU Make 4.x

3.5 本章知识体系

下面这张图把整个环境准备流程串起来了，你可以对照着检查自己做到哪一步了。

3.6 常见问题与避坑

• 虚拟机启动黑屏：检查 BIOS 中是否开启了虚拟化技术（Intel VT-x / AMD-V）。我有一台老笔记本就是默认关闭的，折腾了半天才发现。
• apt update 报 404：源列表中的版本代号（focal/jammy）与系统版本不匹配。用 lsb_release -a 查看当前版本。
• Python 版本冲突：系统自带的 Python 3.8 不要卸载！用 update-alternatives 管理多版本，或者直接用 venv 隔离。
• Git 拉取失败：如果遇到 SSL 证书问题，先执行 sudo apt install ca-certificates 更新证书。