MaaAssistantArknights maa-cli 安装与编译完全指南：预编译、包管理器与 Cargo 源码构建
【免费下载链接】MaaAssistantArknights《明日方舟》小助手，全日常一键长草！| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknights
maa-cli 是 MaaAssistantArknights 官方提供的 Rust 命令行工具，它本身只是一个薄薄的 CLI 外壳，真正执行《明日方舟》自动化任务的是底层 MaaCore 与配套资源。本文以 maa-cli 的官方安装文档 docs/zh-cn/manual/cli/install.md 为骨架，系统梳理预编译二进制、各类包管理器、cargo 源码编译三种安装路线，并完整讲解 MaaCore 与资源的安装前提、编译特性开关及安装后的验证步骤，帮助你在任何主流平台上从零搭建可用的 maa-cli 环境。
maa-cli 与 MaaCore 的依赖关系
在动手安装之前，先明确一个核心概念：maa-cli 只提供命令行界面，不包含任何游戏自动化逻辑。根据 CLI 使用指南 docs/zh-cn/manual/cli/README.md 的说明，maa-cli 的功能有三项：
- 运行预定义或自定义任务，例如
maa fight、maa run <task>； - 通过
maa install和maa update安装、更新 MaaCore 及资源； - 通过
maa self update更新自身。
也就是说，完整的运行链路是maa-cli（命令行入口） → MaaCore（自动化核心） → 游戏资源。MaaCore 本体即本仓库 src/MaaCore 目录下由 C++ 实现的自动化核心（入口见 src/MaaCore/Assistant.cpp），maa-cli 通过其公开的 C 接口（include/AsstCaller.h）驱动任务执行。因此无论采用哪种方式安装 maa-cli，后续都必须另行准备 MaaCore 与资源，这一点在文末专门展开。
方式一：预编译二进制一键安装（最省事）
如果你的平台在官方预编译支持列表中（Linux、macOS、Windows），最简单的方式是使用官方安装脚本一键安装。
Linux 和 macOS使用 curl 下载并执行安装脚本：
curl -fsSL https://raw.githubusercontent.com/MaaAssistantArknights/maa-cli/main/install.sh | bashWindows（PowerShell）先下载脚本再执行：
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/MaaAssistantArknights/maa-cli/main/install.ps1" -OutFile install.ps1; .\install.ps1安装完成后，后续可通过内置的自动更新命令升级 maa-cli 自身：
maa self update注意：maa self update依赖编译时启用的cli_installer特性（见下文"编译选项"），并且对于通过包管理器安装的用户此命令无效——包管理器安装的 maa-cli 应使用对应包管理器来升级（详见 使用文档 中的提示）。
如果你的平台不在预编译列表内，可以跳到文末的 编译安装 章节自行构建。
方式二：包管理器安装
对于 macOS 和受支持的 Linux 发行版，包管理器是更贴合系统惯例的安装方式，且能随系统一并管理升级。
macOS：Homebrew（第三方 tap）
Homebrew 用户可通过官方维护的第三方 tap 安装，提供两个版本可选：
- 稳定版：
brew install MaaAssistantArknights/tap/maa-cli- 不稳定版/预发行版（
maa-cli-beta）：
brew install MaaAssistantArknights/tap/maa-cli-beta在 Linux 上使用 Homebrew 的用户，安装方式与 macOS 完全相同，参见上述命令即可。
Arch Linux：AUR
Arch 用户可直接安装 AUR 包maa-cli，AUR 助手任选其一：
- 使用 paru：
paru -S maa-cli- 使用 yay：
yay -S maa-cliNix / NixOS
Nix 用户可以直接运行，无需事先安装到环境：
- 稳定版（打包在 nixpkgs 中，使用 nixpkgs 提供的 Rust 工具链构建）：
nix run nixpkgs#maa-cli- 每夜构建（位于 NUR 用户仓库，使用 Beta channel 的 Rust 工具链，由 GitHub Actions 每日自动更新与构建验证）：
nix run github:Cryolitia/nur-packages#maa-cli-nightly需要特别注意的是，Nix 上的 maa-cli 对 MaaCore 是强制依赖——即 Nix 打包已把 MaaCore 一并带入，Nix 用户无需也不应该手动再安装 MaaCore（详见下文"安装 MaaCore 与资源"）。
其他发行版
未在上文列表中出现的发行版，请回退使用预编译二进制文件或自行编译安装。项目也欢迎开发者将 maa-cli 提交到更多发行版的官方仓库或用户仓库，扩大覆盖面。
方式三：cargo 编译安装
Rust 开发者可以通过cargo直接从 Git 仓库编译安装，适合需要追踪最新代码、自定义编译特性或平台不在预编译列表中的场景。
- 稳定版本（
--tag stable固定到稳定发布标签）：
cargo install --git https://github.com/MaaAssistantArknights/maa-cli.git --bin maa --tag stable --locked- 开发版本（默认分支最新代码）：
cargo install --git https://github.com/MaaAssistantArknights/maa-cli.git --bin maa --locked两条命令都使用--bin maa指定安装名为maa的可执行文件，--locked锁定依赖版本以保证构建可复现。
最低支持 Rust 版本（MSRV）
maa-cli 目前的最低支持 Rust 版本（MSRV）为1.88。官方明确提示：MSRV 可能随时发生变化，建议始终使用最新的 Rust 工具链以获得最佳体验。如果本机 Rust 工具链过旧，请先通过 rustup 等工具升级。
编译选项（Cargo Features）
从源码编译时，可通过--no-default-features关闭全部默认特性，再用--features按需开启特定特性。当前可用的特性及其作用如下：
| 特性名 | 作用 | 默认状态 |
|---|---|---|
cli_installer | 启用maa self update命令，用于更新 maa-cli 自身 | 默认启用 |
core_installer | 启用maa install和maa update命令，用于安装和更新 MaaCore 及资源 | 默认启用 |
git2 | 提供基于 libgit2 的资源更新后端 | 默认启用 |
实际编译时可按需裁剪，例如仅保留核心功能、去掉自更新能力的构建形如：
cargo install --git https://github.com/MaaAssistantArknights/maa-cli.git --bin maa --no-default-features --features core_installer --locked安装 MaaCore 及资源（运行任务的必要前提）
如开篇所述，maa-cli 只是命令行界面，必须搭配 MaaCore 与资源才能运行任务。这一步根据安装方式与平台的不同，操作略有区别。
预编译 / 自行编译用户：maa install
使用预编译二进制或自行编译安装的用户，可以直接让 maa-cli 帮你完成 MaaCore 与资源的下载安装：
maa install后续需要升级 MaaCore 与资源时，运行maa update即可（相关命令完整说明见 使用文档 的"管理 MaaCore"一节）。这一能力正是由上文编译选项中的core_installer特性提供。
Windows 用户：先装 VC++ 运行库
Windows 平台在运行maa install之前，需要先以管理员身份在命令提示符或 PowerShell 中安装必要组件VC++ 运行库：
winget install "Microsoft.VCRedist.2015+.x64" --override "/repair /passive /norestart" --uninstall-previous --accept-package-agreements --force该命令通过 winget 安装并修复 Visual C++ 2015+ x64 运行库（静默、免重启模式，同时卸载旧版本）。执行完成后，再运行maa install。
Arch Linux 用户：两条路线可选
路线一，直接用 maa-cli 安装官方预编译的 MaaCore：
maa install路线二，通过 AUR 包maa-assistant-arknights安装 maa-core（与 maa-cli 的 AUR 包相互独立）：
paru -S maa-assistant-arknights或：
yay -S maa-assistant-arknightsNix 用户：无需安装
Nix 上的 maa-cli 已强制依赖 MaaCore，因此Nix 用户无需、也不应该手动安装 MaaCore，直接使用即可。
官方预编译版与包管理器版的差异提醒
官方文档特别提醒：maa install下载的是 MAA 官方预编译的 MaaCore，而通过包管理器安装的 MaaCore 可能使用与官方预编译版本不同的编译选项和依赖版本，这可能导致性能和功能上的略微差异。追求与官方一致行为、或需要排查疑难问题时，可优先考虑官方预编译版本。
从仓库侧也可以印证资源体系的组成：资源随 MaaCore 一并由官方构建分发（相关工具见 tools/ResourceUpdater/main.cpp 与 tools/OTAPacker），除随核心安装的基础资源外，还有可单独热更新的资源，可通过maa hot-update手动更新（详见 使用文档 的"其他子命令"一节）。
安装后的验证、初始化与常见问题
验证安装与版本
安装并装好 MaaCore 后，运行以下命令确认 maa-cli 与 MaaCore 均已就绪：
maa version # 获取 maa-cli 与 MaaCore 的版本信息初始化配置
通常完成 MaaCore 安装后无需额外配置即可运行任务，但默认配置未必适合所有人。可通过交互式命令初始化配置：
maa init该命令会引导你交互式配置 MaaCore 相关配置项（配置项详解见 配置文档）。查看配置目录位置可使用maa dir config，日志目录可用maa dir log获取。
macOS 配置目录风格问题
由于 Rust 的 Directories 库在 macOS 上默认使用 Apple 风格目录，maa-cli 在 macOS 上默认采用 Apple 风格配置目录。对命令行程序更习惯 XDG 风格的用户，可以设置XDG_CONFIG_HOME环境变量来切换：
export XDG_CONFIG_HOME="$HOME/.config"如果不想设置环境变量，也可以通过符号链接让$HOME/.config/maa指向 maa-cli 默认配置目录：
mkdir -p "$HOME/.config/maa" ln -s "$HOME/.config/maa" "$(maa dir config)"更多细节见 常见问题。
小结：如何选择安装方式
| 场景 | 推荐方式 | 后续 MaaCore 安装 |
|---|---|---|
| Linux / macOS / Windows 常规用户 | 安装脚本（预编译） | maa install |
| macOS（Homebrew 用户） | brew install MaaAssistantArknights/tap/maa-cli | maa install或依赖包内 MaaCore |
| Arch Linux | AUR（paru/yay） | maa install或 AURmaa-assistant-arknights |
| Nix / NixOS | nix run nixpkgs#maa-cli或 NUR 每夜版 | 无需（强制依赖） |
| Rust 开发者 / 其他平台 | cargo install（stable 或 dev 分支） | maa install |
无论选择哪条路线，最终落地形态都是同一个maa命令；装好 MaaCore 后即可参考 使用文档 运行maa startup、maa fight等预定义任务或maa run <task>自定义任务。若在安装过程中遇到平台适配问题，可先核对本文所述的平台差异（VC++ 运行库、Nix 强制依赖、AUR 双包等），再对照 常见问题 排查。
【免费下载链接】MaaAssistantArknights《明日方舟》小助手，全日常一键长草！| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknights
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
