maa-cli 配置目录完全指南在 macOS 上启用 XDG 风格的$HOME/.config/maa【免费下载链接】MaaAssistantArknights《明日方舟》小助手全日常一键长草| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknightsmaa-cli 是 MAAMaaAssistantArknights项目的 Rust 命令行客户端用于调用 MaaCore 自动化完成《明日方舟》日常任务如maa fight、maa run task并提供 MaaCore 安装更新、任务调度与结果汇总能力。本文聚焦 maa-cli 配置目录机制重点解答官方 FAQ 中的经典问题——如何在 macOS 上让 maa-cli 使用$HOME/.config/maa作为配置目录并在此基础上延伸讲解配置目录的完整结构、相关命令与配置文件布局帮助你彻底掌握 maa-cli 的目录与配置管理。为什么 macOS 上的配置目录是个问题maa-cli 是用 Rust 编写的命令行程序它通过 Rust 生态的 Directories 库解析系统目录。该库在 macOS 上遵循 Apple 的约定默认把应用配置放在~/Library/Application Support之类的 Apple 风格目录中。因此maa-cli 在 macOS 上默认也采用 Apple 风格目录存放配置。对于桌面 GUI 应用而言Apple 风格目录是合理的但对于命令行程序XDG 风格Linux 系约定即$HOME/.config/应用名明显更适合终端用户配置集中在~/.config下便于备份、同步和版本管理与 Linux 上 maa-cli 的行为保持一致跨平台迁移配置更轻松许多 CLI 工具链git、ripgrep 等都遵循 XDG 约定习惯一致。关于 maa-cli 的功能定位可参考 CLI 手册首页它用 Rust 实现支持运行预定义或自定义任务如maa fight或maa run task、通过maa install/maa update安装更新 MaaCore 与资源、并通过maa self update自我更新。如何查看当前配置目录在动手调整之前先确认 maa-cli 当前实际使用的配置目录。maa-cli 提供专门的子命令maa dir config该命令会输出 maa-cli 当前使用的配置目录绝对路径。在 macOS 上未做任何设置时输出通常是~/Library/Application Support/maa之类的 Apple 风格路径。这正好是官方 FAQ 中问题的前提你希望改用它作为 XDG 风格目录的$HOME/.config/maa。解决方案一通过环境变量XDG_CONFIG_HOME指定最简单、最干净的方案是设置XDG_CONFIG_HOME环境变量。只要把它指向$HOME/.configmaa-cli 就会遵循 XDG 规范把配置目录解析为$HOME/.config/maaexport XDG_CONFIG_HOME$HOME/.config这一方案的本质是Directories 库在检测到XDG_CONFIG_HOME已被显式设置时会优先采用 XDG 逻辑而非 macOS 的 Apple 风格逻辑因此 maa-cli 的配置目录会随之为$XDG_CONFIG_HOME/maa。为了让配置永久生效需要把该行写入 shell 的启动脚本。例如 zsh 用户写入~/.zshrcbash 用户写入~/.bashrc# ~/.zshrc 或 ~/.bashrc export XDG_CONFIG_HOME$HOME/.config保存后执行source ~/.zshrc或重新打开终端再用下面的命令验证maa dir config # 期望输出: /Users/你的用户名/.config/maa注意XDG_CONFIG_HOME是一个全局环境变量会影响其他遵循 XDG 规范的程序的配置解析路径大部分遵循 XDG 的程序本来就默认使用~/.config所以通常不会有副作用但如果你对某个程序的目录有特殊定制需自行确认兼容性。解决方案二创建符号链接不修改环境变量如果你不想引入全局环境变量官方 FAQ 给出了第二种方案——创建符号链接让 maa-cli 默认的 Apple 风格配置目录指向$HOME/.config/maamkdir -p $HOME/.config/maa ln -s $HOME/.config/maa $(maa dir config)命令解读mkdir -p $HOME/.config/maa先创建 XDG 风格的配置目录-p保证中间目录不存在时自动创建$(maa dir config)命令替换动态获取 maa-cli 当前解析出的配置目录路径即 Apple 风格路径如~/Library/Application Support/maaln -s ... ...创建从 XDG 目录到 maa-cli 实际读取目录的符号链接之后 maa-cli 无论读写哪个文件最终都会落到$HOME/.config/maa中。创建完成后你的所有 maa-cli 配置文件任务文件、profiles 等都统一收纳在$HOME/.config/maa下备份或迁移时只需拷贝这一目录。验证与补充配置目录相关命令一览除maa dir config外maa-cli 的maa dir子命令还支持查询其他目录。结合 使用文档 可知maa dir config配置目录maa dir log日志目录配合--log-file使用时日志默认写入$(maa dir log)/YYYY/MM/DD/HH:MM:SS.logmaa dir hot-update资源热更新仓库的存放位置在配置远程仓库后可用于定位资源库。此外配置目录本身还可以通过环境变量MAA_CONFIG_DIR直接覆盖见 配置文档即MAA_CONFIG_DIR的优先级高于XDG_CONFIG_HOME推导结果。因此完整的目录解析优先级可归纳为MAA_CONFIG_DIR显式指定XDG_CONFIG_HOME推导XDG 风格 平台默认macOS 为 Apple 风格。延伸配置目录内部结构理解配置目录落在哪里之后还需要知道里面该放什么。根据 配置文档$MAA_CONFIG_DIR即你最终确定的配置目录下通常包含以下内容路径用途tasks/自定义任务文件maa run task以去掉扩展名的文件名作为任务名执行profiles/MaaCore 配置称为 Profile默认使用default.toml可用-p/--profile切换cli.tomlmaa-cli 自身的更新渠道、资源热更新等配置infrast/自定义基建排班计划文件相对路径以此为基准ssscopilot/保全派驻SSS作业文件相对路径以此为基准resource/当 profile 中user_resource true时加载的用户自定义资源配置文件本身支持 TOML、YAML、JSON 三种格式可以混合使用只要扩展名正确即可。例如一个典型的 MaaCore profileprofiles/default.toml如下[connection] preset MuMuPro adb_path adb address emulator-5554 config CompatMac [resource] global_resource YoStarEN platform_diff_resource iOS user_resource true [static_options] cpu_ocr false gpu_ocr 1 [instance_options] touch_mode MaaTouch deployment_with_pause false adb_lite_enabled false kill_adb_on_exit false上述配置在 macOS 上尤其有意义config CompatMac是 macOS 平台的默认连接配置而platform_diff_resource iOS对应 iOS 客户端的差异化资源。这正说明把配置目录统一到 XDG 风格后你可以更方便地用版本管理工具如 git追踪这些关键配置。结合源码理解目录解析的实现依据从仓库结构看maa-cli 的相关文档集中在 docs/en-us/manual/cli/ 目录README、install、usage、config、faq 五份文档而其安装与编译入口说明可见 安装与编译文档——其中明确指出 maa-cli 的 MSRV最低支持 Rust 版本当前为 1.88且cli_installer、core_installer、git2libgit2 资源更新后端三个 feature 默认开启。可以推断配置目录的解析逻辑在 maa-cli 的 Rust 源码中位于maa-clicrate 内依赖directoriescrate 完成平台路径判定这正是 FAQ 中macOS 默认使用 Apple 风格目录结论的来源。值得注意的是当前仓库中的 src/maa-cli/ 目录为空占位maa-cli 作为独立项目维护本仓库内提供的是其面向用户的完整文档体系。因此本文涉及的命令与行为均以本仓库 CLI 文档 为准。常见问题排查改了环境变量后maa dir config没变化确认环境变量是否已在当前 shell 生效echo $XDG_CONFIG_HOME并确认没有同时设置MAA_CONFIG_DIR它优先级更高。符号链接方案下如何撤销删除符号链接即可恢复 Apple 风格目录若$HOME/.config/maa已积累配置建议先备份再处理。配置迁移后任务找不到检查tasks/、profiles/、infrast/等子目录是否已同步迁移自定义基建计划的filename相对路径以$MAA_CONFIG_DIR/infrast为基准见 配置文档。总结macOS 上 maa-cli 的配置目录默认遵循 Apple 风格这对命令行程序不够友好。官方 FAQ 给出了两条清晰的解决路径设置XDG_CONFIG_HOME环境变量或通过ln -s创建符号链接二者最终都能让 maa-cli 把配置统一收纳到$HOME/.config/maa。在此基础上理解maa dir config、MAA_CONFIG_DIR的解析优先级以及tasks/、profiles/、cli.toml等目录结构就能在任何平台上把 maa-cli 的配置管理得井井有条并借助 XDG 约定轻松实现配置的备份与同步。【免费下载链接】MaaAssistantArknights《明日方舟》小助手全日常一键长草| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknights创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考