刚接触 Android SDK 命令行工具的人十有八九会在第一次执行sdkmanager时撞到一个看起来很吓人、其实很莫名其妙的提示Warning: Could not create settings。我第一次遇到它是在一台刚装好 JDK 的虚拟机上当时以为安装包坏了重新解压了好几次问题照旧。后来把 Java 的偏好设置机制、SDK 目录规范和许可证流程翻了个遍才算真正看清楚这行 Warning 的来路。这篇文章就把这段排查经历完整写出来给同样被它卡住的朋友一条可以直接照做的路径。文章会从报错的底层原因讲起再讲 JDK、目录结构、环境变量这些前置条件然后给出完整的排查顺序和分平台解决方案。无论你是第一次使用命令行工具链还是在 CI 脚本里反复看到这行提示按下面的顺序逐项排掉基本能一次解决。1. 先别急着改配置搞清楚“Could not create settings”到底卡在哪1.1 报错现场与触发规律这个警告最常出现的场景有三个第一次运行sdkmanager的全新环境、用户目录权限被改乱过的旧环境、以及容器或虚拟机上以 root 身份运行的环境。终端里通常会长这样Warning: Could not create settings java.lang.IllegalStateException: BackingStoreException at java.util.prefs.FileSystemPreferences.syncWorld at java.util.prefs.FileSystemPreferences.flush ...麻烦的地方在于这行 Warning 出现之后sdkmanager并不会马上退出它可能照常打印版本号甚至能列出部分软件包。于是很多人觉得“反正只是警告”继续往下装东西结果后面蹦出来一堆更奇怪的错误许可证反复要求确认、组件下载到一半失败、SDK 目录里写不进文件。这里的关键规律是Warning 本身只是表象真正要关注的是“这个工具到底有没有能力保存状态”。如果保存状态这条路被堵死很多后续操作都会在暗处出错。1.2 底层机制sdkmanager 用 Java 偏好设置存状态sdkmanager本身是用 Java 写的启动时它要读取和保存用户偏好设置这些设置包括许可证协议是否接受、历史配置、窗口状态等。Java 的 Preferences API 默认把用户级数据放在两个位置Unix 系系统$HOME/.java/.userPrefs/目录下的 XML 文件Windows 系统注册表HKCU\Software\JavaSoft\Prefs子树正常情况下Java 运行时会自动创建这些路径。但一旦用户目录不存在、不可写或者注册表对应的键被策略锁住Preferences API 就会抛出异常。sdkmanager对异常做了捕获没有让进程直接崩溃而是降级成一行 Warning 继续运行。理解这一层之后后续的解决思路其实就浓缩成一句话给 Java 的偏好设置找一个能真正写入的位置。触发场景直接原因修复方向全新环境首次运行$HOME下没有.java目录且自动创建失败手动创建目录并授权使用 sudo/root 运行HOME指向了不可写目录保留原环境变量或显式设置 HOMEWindows 注册表受限HKCU\Software\JavaSoft被策略锁定用环境变量把 prefs 指到文件目录容器只读文件系统根目录或用户目录不可写挂载可写卷并设置 prefs 位置1.3 这个警告是“小毛病”还是“大问题”如果sdkmanager只是打印 Warning但--version、--list都正常而你只是临时查一下组件列表那它可以先放着不管。但如果接下来要做这几件事就必须处理接受许可证协议安装或更新 SDK 组件在 CI 脚本中自动执行构建相关命令原因很简单许可证的“已接受”状态就是靠这套 Preferences 机制持久化的。状态写不进去等于每次都要重新接受一遍或者每次都拿不到完整的软件包列表。与其等到 CI 流水线里爆发不如一开始就把这个坑填平。2. 基础底子没打好sdkmanager 后面还会有一堆连锁问题2.1 JDK 版本多数人栽在这里Android 官方近几年发布的命令行工具包内置的sdkmanager基本上默认要求 JDK 17。如果你的机器上还在用 JDK 8 或 JDK 11可能不会立刻收到一句友好的“版本太低”提示而是先遇到一串类加载异常或者一堆让人摸不着头脑的报错。执行下面这条命令先确认 Java 版本java -version不同情况的参考判断如下环境中的 JDK现象建议JDK 17正常使用保持即可JDK 11部分可用可能偶发异常建议升级到 17JDK 8 或更老各种诡异报错直接装 JDK 17只有 JRE运行时找不到类安装完整 JDK安装 JDK 17 之后务必设置JAVA_HOME并且把它加进PATH。Windows 用户还要注意改完环境变量后必须新开一个 cmd 或 PowerShell 窗口让新配置真正生效。很多人改了系统变量后直接在旧窗口里重试当然还是报错。2.2 cmdline-tools 目录放置目录结构不对位置全乱这个坑非常隐蔽。从官网下载的 zip 解压以后第一层目录就是cmdline-tools里面才是bin、lib等子目录。规范的做法是把它移动到 SDK 根目录下的cmdline-tools/latest/里最终形成这样的结构SDK_ROOT/ ├── cmdline-tools/ │ └── latest/ │ ├── bin/ │ │ ├── sdkmanager │ │ ├── sdkmanager.bat │ │ └── avdmanager │ ├── lib/ │ └── ... ├── build-tools/ ├── platforms/ └── platform-tools/如果你直接解压成SDK_ROOT/cmdline-tools/bin/这种结构工具链会认为目录不完整随后报出各种连锁错误。因为工具链默认用latest这个固定路径寻找可执行文件版本号目录只是供多版本并存用的没有latest这一层它根本不知道去哪个目录找入口。Linux 和 macOS 上建议用mv把内容移动到目标位置Windows 上先解压到临时目录再把内部文件移动过去。千万别图省事把 zip 内容直接全部倒在 SDK 根目录下那样必然出问题。2.3 环境变量和 --sdk_root 的关系sdkmanager在定位 SDK 根目录时会先看命令行参数再看环境变量最后才会根据自身路径反推。命令行参数的优先级最高。为了避免意外我建议在任何脚本里都显式传--sdk_root而不是依赖环境变量同时把ANDROID_SDK_ROOT也设成同一个值。这样无论哪个环节读取配置拿到的根目录都是一致的不会出现“这个命令认一个目录、那个命令认另一个目录”的混乱。另外ANDROID_HOME是旧名称很多老教程还在用。虽然新版本工具不一定依赖它但为了兼容旧脚本最好也一并设成相同路径。三个位置统一之后很多看似随机出现的错误会直接消失。3. 完整排查链路从看到警告到恢复正常跑通的每一步3.1 先用一条命令判断是环境问题还是工具问题不要一上来就删目录重装。先在一个终端里依次执行下面这几条把输出记下来java -version echo JAVA_HOME$JAVA_HOME echo ANDROID_SDK_ROOT$ANDROID_SDK_ROOT echo ANDROID_HOME$ANDROID_HOME echo HOME$HOME sdkmanager --version如果sdkmanager --version本身能输出版本号说明可执行文件是好的问题集中在环境或偏好设置上。如果连版本都出不来先检查 JDK 和目录结构。这一步看起来简单但确实能帮你少走很多冤枉路。我见过有人花一晚上重装系统依赖最后发现只是 cmd 窗口没重开JAVA_HOME还是空的。3.2 给 Java 偏好设置一个能落脚的目录确认HOME指向一个真实存在、可写的目录之后手动创建userPrefs目录并检查当前用户有没有写权限mkdir -p $HOME/.java/.userPrefs chmod 700 $HOME/.javaWindows 上通常不需要这一步因为偏好设置写的是注册表。但如果遇到过注册表被策略锁定的情况可以用环境变量强制 Java 把偏好设置写到文件目录里export JAVA_TOOL_OPTIONS-Djava.util.prefs.userRoot$HOME/.java/.userPrefs把这条export写进 shell 配置文件或者在 CI 脚本开头执行。这样sdkmanager就会把偏好设置写到$HOME/.java/.userPrefs下的文件里不再依赖系统默认位置Windows 上也能避开注册表限制。3.3 接受许可证一个被忽略的隐藏入口很多人以为--licenses只是同意几个协议其实这个动作会真实地写入许可证状态而写入行为正好依赖上面说的 Preferences 机制。如果 preferences 写不进去你就算当场按着 y 过完所有协议下次执行命令时它依然会提示你没接受。正确顺序是先解决userPrefs的可写问题再一次性接受许可yes | sdkmanager --sdk_root$ANDROID_SDK_ROOT --licenses执行时不需要盯着屏幕结束提示出现之后就说明状态已经写入。如果没有正常结束回头检查上一步的目录权限多半是某个路径没有写权限。3.4 把 SDK 根目录写在明处接下来执行任何sdkmanager命令都显式加上--sdk_root防止它跑偏$ANDROID_SDK_ROOT/cmdline-tools/latest/bin/sdkmanager \ --sdk_root$ANDROID_SDK_ROOT \ --list这样即使环境变量在某个脚本里被临时覆盖命令行参数仍然能保证它指向正确的根目录。这个习惯在 CI 场景里尤其重要因为构建服务器的环境经常被多个脚本共用环境变量被覆盖是常有的事。3.5 验证能列包、能安装、能接受许可证修复完成之后做三步验证缺一不可列包执行--list能正常输出组件列表安装装一个体积很小的组件比如platform-tools确认能写入 SDK 目录再验许可再次执行--licenses确认没有反复提示同意协议都通过后那个 Warning 基本就会消失。如果 Warning 还在但功能完全正常那说明还有别的东西在控制 Java 的 prefs 路径可以接着看下一章的专题排查。4. 分平台破案Windows 注册表、macOS 路径、容器环境各有各的坑4.1 Windows权限是万恶之源Windows 上最容易踩的坑是把 SDK 根目录选在了系统保护目录下。把cmdline-tools解压到C:\Program Files\Android\Sdk后普通用户运行sdkmanager时根本没有写权限各种报错就会以千奇百怪的形式冒出来。建议直接把 SDK 放在C:\Android\Sdk或者%USERPROFILE%\Android\Sdk这类普通用户可写的路径尽量避免带空格的 Program Files 路径。在 cmd 里执行sdkmanager.bat之前先确认新开的窗口里JAVA_HOME是否生效echo %JAVA_HOME%如果显示为空设置完环境变量后要重新开 cmd。注册表问题比较少见但在公司统一管理的机器上组策略确实可能锁定HKCU\Software\JavaSoft子树。这时候用JAVA_TOOL_OPTIONS把 prefs 指到文件目录是唯一的绕行办法。4.2 Linux/macOSHOME 与 .java 目录的隐形地雷Linux 上最常见的坑是 sudo。你明明是当前用户但执行sudo sdkmanager ...之后HOME可能变成/root而/root下可能没有.java目录或者/root本身权限设置很严。解决方案是尽量不用 sudo 执行sdkmanager如果非要用就加上-E参数保留原有环境变量sudo -E sdkmanager --sdk_root$ANDROID_SDK_ROOT --listmacOS 上要特别注意JAVA_HOME的路径它通常指向/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home而不是外层目录。还有一种情况是自动挂载的 home 目录在初始化时没有执行.zshrc或.bashrc导致PATH缺了 JDK 路径。出现奇怪报错时先跑一遍which java确认实际指向的是哪个 JDK 再往下查。4.3 Docker/CI 与无显示环境三种额外配置别漏容器环境里这个警告几乎必现根因基本都在于没有给 Java 一个可写的 HOME。我常用的组合有四个明确设置ENV HOME/root或/home/builder并保证对应目录存在启动脚本里先执行mkdir -p $HOME/.java/.userPrefs所有sdkmanager命令都带--sdk_root许可证接受过程用yes |非交互式处理另外基础镜像里要提前装好unzip和ca-certificates。缺解压工具会出现 zip 打不开的诡异现象很容易让人误判成别的错误。如果容器以只读文件系统运行SDK 目录必须挂成可写卷否则任何写入都会被拒绝那已经不只是 prefs 层面的问题了。5. 让这个报错从此消失一份可直接套用的初始化脚本与日常维护习惯5.1 一个跨平台的检查脚本骨架下面这段脚本适合 Linux 和 macOS我经常把它放到新环境的初始化步骤里。它不算最精简但每一步都有明确目的#!/usr/bin/env bash set -euo pipefail SDK_ROOT${ANDROID_SDK_ROOT:-$HOME/Android/Sdk} export ANDROID_SDK_ROOT$SDK_ROOT # 1. 给 Java 偏好设置留好位置 mkdir -p $HOME/.java/.userPrefs # 2. 确认 cmdline-tools 目录结构 CMDTOOLS$SDK_ROOT/cmdline-tools/latest if [ ! -x $CMDTOOLS/bin/sdkmanager ]; then echo sdkmanager not found under $CMDTOOLS/bin exit 1 fi # 3. 检查 JDK java -version # 4. 非交互接受许可 yes | $CMDTOOLS/bin/sdkmanager --sdk_root$SDK_ROOT --licenses # 5. 列出组件验证 $CMDTOOLS/bin/sdkmanager --sdk_root$SDK_ROOT --listWindows 上把命令换成sdkmanager.bat把$HOME改成%USERPROFILE%思路完全一样。这套脚本跑完通常不会再出现Could not create settings。5.2 日常维护升级、更新与清理升级cmdline-tools时不要直接覆盖latest目录最好把新下载的 zip 解压到临时目录确认没问题后整体替换。如果.java/.userPrefs里的 XML 文件被写坏了或者你想彻底重置偏好可以先把该目录改名备份再让 Java 自动重建这比反复猜测配置内容可靠得多。SDK 组件更新用sdkmanager --update也可以但建议在重要项目里手动看一遍变更内容避免工具链突然跨大版本导致构建行为变化。别小看这些日常小事很多潜伏问题都是组件版本不一致引出来的。5.3 警告还在但功能正常要不要继续管如果你只是偶尔手动跑一条命令并且确认列表、安装、许可都没有问题留着这行 Warning 也无所谓。但如果它出现在自动化流水线里我还是建议花几分钟处理掉。流水线日志里的 Warning 很容易被误判成失败原因到时候排查起来成本比修复成本还高。我自己的习惯是只要报错信息里出现Could not create settings就先检查userPrefs和--sdk_root两处几乎五分钟内能解决。最后说一点个人体会这类问题最迷惑人的地方在于它不会让命令立刻崩掉而是留着一个看似无害的 Warning 让你继续往前走。真正被它坑到的时候往往是半个月后你在 CI 日志里发现许可证状态丢失、组件装了一半失败回溯之后才发现源头就是当初那行不起眼的提示。所以遇到它不值得绕路。按照“基础环境、目录结构、偏好设置、许可状态”这个顺序查一遍后续所有依赖sdkmanager的操作都会顺畅很多。