Mojo编程实战二：环境搭建与工具链

第 2 章 环境搭建与工具链

本章目标 – 在 macOS / Linux / Windows（WSL2）上把 Mojo 1.2.0 装好，并说清每一步为什么这么做。 – 搞懂 Mojo SDK 与 MAX SDK 的区别，知道什么时候只装 mojo、什么时候要装 max[all]。 – 把 mojo CLI 的八个子命令用顺：run、build、repl、debug、precompile、format、doc、demangle。 – 配好 VS Code 开发环境，并知道在线 Playground 已经没了。 – 走完 Hello World 全流程，并亲手搭一个多文件的 Mojo 包项目。

2.1 先确认你的机器能不能跑

Mojo 不是\”Windows 装个 exe、一路下一步到底\”的生态。在敲任何安装命令之前，先对着下表核对平台（要求基于 2026 年 10 月官方文档）：

宿主 Python 解释器要求 3.10 到 3.14。这里要解释一下\”宿主 Python\”这个词——Mojo 自己是编译型语言，运行程序并不依赖 Python；但它现在打包在 Python 生态里（就是一个 pip/conda 包），所以落地时要借一套现成的 Python 环境。这也是为什么安装方式一节全是 uv、pixi 这类 Python 包管理器。

顺带说清两个常见疑问：手里是 Intel 芯片老 Mac 的读者，官方没有原生支持，现实的做法是用一台云 Linux 机器或 WSL 远程开发；而 Linux 这边目前只出 x86-64 构建，ARM 版（比如树莓派、AWS Graviton）还不在官方支持矩阵里。这些边界短期内不会变，选机器时先按表核对，别装好半天发现架构不对。

踩坑提示：Windows 用户最容易卡在这一步。先在 PowerShell 里跑 wsl –status，确认默认版本是 WSL2 而不是 WSL1；再进入 WSL 跑一句 ldd –version，主版本号 ≥ 2.34 才满足 glibc 要求。如果你现有的 WSL 发行版太老（比如几年前导入的老 Ubuntu），别想着在里面硬凑，直接 wsl –install Ubuntu-22.04 装一个新的，否则后面 mojo 命令会报一堆动态库找不到的错。GPU 驱动装在 Windows 宿主侧，WSL 里不用重装 NVIDIA 驱动——但那属于 MAX 的事，本章先不管。

安装之前再花一分钟理清两个 SDK 的关系，不然装的时候会糊涂：

• Mojo SDK：就是 pip/conda 里那个叫 mojo 的包。它包含 mojo CLI（编译器）、标准库、语言服务器 LSP、LLDB 调试器、代码格式化器和 REPL。这本书前 15 章你只需要它。
• MAX SDK：pip 包叫 max，全装写法是 max[all]，是高通 / Modular 的 AI 推理与加速器平台。它会连带把 mojo 也装上。只有当你要写 GPU 自定义算子（max.gpu）、用 max serve 部署模型时才需要它。

一句话：学语言装 mojo，做 GPU / 模型部署装 max[all]。

另外提一句容易被忽略的事：Mojo SDK 默认会收集崩溃报告和语言服务器的响应延迟，用于改进工具链——它不会上传你的源码或按键内容。如果你的开发环境对数据出境敏感，可以在装好后查官方文档里的遥测开关把它关掉，这不影响编译和运行。

2.2 方案一：用 uv 安装（推荐）

uv 是 Astral 出的 Python 包管理器，用 Rust 写的，比传统 pip 快一两个数量级，并且和 pip 生态完全兼容。Mojo 现在就是一个普通的 PyPI 包，所以装它跟装 requests 没本质区别。

还没有 uv 的话，先按官方 README 的标准方式装一个：

curl -LsSf https://astral.sh/uv/install.sh | sh

装 Mojo 有两种用法，我更建议第二种。

全局装进当前 Python 环境：

uv pip install mojo

在项目里装（隔离环境，推荐）：

uv init hello-world cd hello-world uv add mojo

uv init 会生成一个带 pyproject.toml 的空项目和一个 .venv 虚拟环境；uv add mojo 把 Mojo 装进这个项目专属的环境里。好处很实际：不同项目可以钉不同的 Mojo 版本，升级、回滚都不互相污染。Mojo 现在大约六周一个稳定版，项目级锁定能帮你挡住\”莫名其妙升级了就编译不过\”这类事。

装好之后，mojo 命令就在项目的 .venv/bin/mojo