简介Android Studio Dolphin (2021.3.1) Beta 1 的 macOS 安装包面向使用 x86_64 架构 Mac 的 Android 开发者适合需要独立安装、离线备份或保留特定历史版本 IDE 的场景。压缩包内完整集成开发环境及运行依赖共 2000 个文件包含大量 Python 脚本、Java 归档jar、JSON 配置、ttf/otf 字体、WebP 图片、SO 动态库及 macOS 专用 dylib 等覆盖 IDE 主程序、构建工具链、调试器、许可证文件与各类资源组件整体大小约 981.54MB。该版本属于 Android Studio Dolphin 系列与后续 Electric Eel、Chipmunk 等版本形成清晰迭代链可作为环境对比、历史版本留存或旧版项目兼容性测试的参考。目前已有 576 人学习下载适合对稳定版本有偏好、或需在旧版 macOS 环境中配置 Android 开发环境的读者。1. Dolphin 到底是个什么版本为什么 2021.3.1.10 值得单独说Android Studio Dolphin也就是android-studio-2021.3.1.10-mac.zip对应的版本是很多 Mac 开发者在 2021 到 2022 年间从老项目升级时绕不开的一个稳定分支。它的内部版本号是 2021.3.1补丁号 10使用 Dolphin 作为代号。很多人看到这个版本号会以为它已经过时但它恰好覆盖了 AGP 7.1 和 Compose 1.1 的支持区间对旧工程兼容性比后来的 Chipmunk 更宽容又是少数还在为 Intel Mac 做打包适配的版本。这篇文章会把 macOS 上从解压 zip、配 SDK 到跑通一个项目的完整过程走一遍重点落在参数和报错上适合手里还有 2020 年前后工程、暂时不想升级 AGP 8.x 的人参考。2. Mac 上解压、安装与首次启动从 zip 到可用拿到android-studio-2021.3.1.10-mac.zip后Mac 用户最容易遇到的问题是双击解压后 app 提示已损坏或者在右键菜单里只有“移到废纸篓”。这不是包的问题而是 macOS 对下载文件的 quarantine 隔离机制。Dolphin 这个版本在签名和公证上的处理和后来版本不太一样需要手动解除隔离属性才能稳定启动。2.1 为什么 Dolphin 的 mac 包是 zip 而不是 dmgAndroid Studio 从 Arctic Fox 开始macOS 分发格式从 dmg 切到了 zip。原因并不复杂dmg 挂载后才能解包在 CI 和命令行脚本里还要处理卷挂载和卸载zip 直接unzip就能用。Dolphin 这个包名里mac表示 macOS 平台而不是 Linux 或 Windows 版本。用 Finder 双击 zip 解压会得到Android Studio.app但解压出的文件会带上com.apple.quarantine属性这会导致启动时被 Gatekeeper 拦下来。2.2 从终端解压并安装到 /Applications我一般建议直接用终端解压而不是在 Finder 里双击。一是能看清解压后实际目录名二是可以立刻执行后面的xattr命令。cd ~/Downloads unzip -q android-studio-2021.3.1.10-mac.zip mv Android Studio.app /Applications/unzip -q里的-q是 quiet如果不加解压几千个小文件时终端会滚屏浪费时间也看不清错误。mv到/Applications是为了让后续的命令行工具能用稳定路径也避免部分脚本因路径中有空格而出错。移动完成后用ls /Applications | grep Android Studio确认。接着处理隔离属性xattr -dr com.apple.quarantine /Applications/Android Studio.appxattr的-d删除指定键-r递归处理整个 app 包。这一步执行后再打开不会弹出“已损坏”或要求右键打开。如果跳过你会在右键菜单里反复找“打开”即使打开了下次启动还是老样子。2.3 使用 sdkmanager 预装 SDK 和命令行工具第一次启动 Dolphin 时安装向导会帮你下载 SDK但在国内网络环境下向导里的进度条经常卡住还会遇到搜索“android studio sdk无法勾选”时描述的情况。更常见的做法是先不启动 Studio用命令行工具把 SDK 目录搭好。mkdir -p $HOME/Library/Android/sdk/cmdline-tools # 从 Android Studio 下载页拿到 commandlinetools-mac-* zip unzip -q commandlinetools-mac-*_latest.zip -d $HOME/Library/Android/sdk/cmdline-tools mv $HOME/Library/Android/sdk/cmdline-tools/cmdline-tools $HOME/Library/Android/sdk/cmdline-tools/latest这里的目录结构很关键。sdkmanager 只认cmdline-tools/latest/bin这个路径如果直接解压到cmdline-tools/bin后面所有命令都会报错。解压出来的目录名默认是cmdline-tools把它重命名为latest才能被工具链识别。接着安装许可证和核心组件yes | $HOME/Library/Android/sdk/cmdline-tools/latest/bin/sdkmanager --licenses $HOME/Library/Android/sdk/cmdline-tools/latest/bin/sdkmanager \ platforms;android-31 \ build-tools;30.0.3 \ platform-toolsyes |自动接受所有许可证协议否则要手动按二十多次 y。platforms;android-31是 API 31 的 SDK 平台Dolphin 默认的 targetSdk 就是这个build-tools;30.0.3是 Dolphin 时代 AGP 7.1 的默认构建工具比它低会在构建时报 warning比它高一些也不是不行但 30.0.3 最稳。platform-tools提供adb、aapt等命令。2.4 首次启动时手动指定 SDK 路径预装完 SDK 后启动 Dolphinopen /Applications/Android Studio.app如果向导里检测不到 SDK进入Settings Appearance Behavior System Settings Android SDK把Android SDK location设成$HOME/Library/Android/sdk。只做 GUI 操作不放心的话可以在终端先验证$HOME/Library/Android/sdk/platform-tools/adb version输出Android Debug Bridge version 1.x就说明 SDK 工具链可用。Dolphin 到这一步已经算装完了接下来真正的问题都出在 JDK、Gradle 和项目的版本匹配上。3. SDK、JDK 与 Gradle 的绑定关系把环境配到不会炸Dolphin 的很多配置问题其实不是 Studio 本身造成的而是项目里的 Gradle 版本和 AGP 版本与它默认值不一致。新版 Android Studio 会主动迁移 wrapperDolphin 反而卡在中间状态需要手动对齐三个版本。3.1 三个关键版本配对表组件Dolphin 推荐值说明JDK11Studio 自带 JBR低于 11 编译 AGP 7.1 会直接报错Gradle7.2 7.4.27.0 以下对 AGP 7.1 支持不完整AGP7.1.0 7.1.47.2 以上需要更新的 StudioBuild Tools30.0.3与 AAPT2 的资源处理行为直接相关版本配对原则很简单AGP 决定最低 Gradle 版本Gradle 又决定能否被 Studio 识别。如果你项目里的gradle-wrapper.properties写的是 7.5 或 8.xDolphin 打开后虽然也能跑但会触发 AGP 升级提示反过来一个 AGP 8.x 的工程拿到 Dolphin 里会直接提示Minimum supported Gradle version is 8.0。遇到这种情况别硬调 Gradle换新版本 Studio 更省事。3.2 环境变量哪些必须写进 profile在~/.zshrc里加环境变量很多人加了也报错先看路径是否写对export JAVA_HOME/Applications/Android Studio.app/Contents/jbr/Contents/Home export ANDROID_HOME$HOME/Library/Android/sdk export PATH$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$PATHJAVA_HOME指向 Dolphin 自带的 JetBrains Runtime路径里的Contents/jbr在 Intel 和 Apple Silicon 都是一样的位置。这个设置只对从终端启动的程序生效像是./gradlew、adb、emulator都会继承。ANDROID_HOME是 Flutter、React Native、Cordova 这些跨平台框架在 macOS 上都会读取的变量。PATH里的platform-tools让你不用敲全路径就能执行adbemulator目录放进去是为了后续命令行启动模拟器。提示如果你机器上装了独立 JDK 17JAVA_HOME可以指到它但 Gradle 的 JVM 参数里要加-Duser.home和模块开放参数否则 Kotlin 编译时会出现Unsupported class file major version 61。我一般就用 Studio 自带的 JBR 11省去这类麻烦。3.3 用 init.gradle 把依赖下载速度提上来“Gradle sync 太慢”在 mac 上很常见尤其是在国内网络环境。常见做法不是改每个项目的仓库地址而是写一个全局初始化脚本让所有项目都先走镜像。在~/.gradle/init.gradle中写入allprojects { repositories { maven { url https://maven.aliyun.com/repository/google } maven { url https://maven.aliyun.com/repository/central } maven { url https://maven.aliyun.com/repository/gradle-plugin } maven { url https://maven.aliyun.com/repository/public } } }allprojects下的repositories会应用到每个模块把google()和mavenCentral()替换成镜像源。仓库顺序有讲究google 放最前否则中央仓库里的旧版本可能被优先命中。放到init.gradle后不需要改项目的build.gradleApp 和 Library 模块都能吃到。Gradle 分发本身下载慢要改gradle-wrapper.propertiesdistributionUrlhttps\://mirrors.cloud.tencent.com/gradle/gradle-7.4.2-bin.zipdistributionUrl是 wrapper 启动时下载 Gradle 压缩包的地址bin表示不带源码和文档的二进制版本。默认域名换成镜像后首次 sync 的等待时间能缩短到原来的三分之一。3.4 SDK 无法勾选时怎么用命令行绕过SDK Manager 里有的组件是灰色不可勾选的比如某些 system-image 只显示 Installed 但不能切换版本或者Android SDK Command-line Tools整行灰掉。多数情况是因为这个组件作为依赖已经以某个版本存在了。在 SDK Manager 右下角打开Show Package Details就能看到每个包的具体版本。如果还不行直接用 sdkmanager 强制处理sdkmanager --list_installed sdkmanager --install build-tools;30.0.3 sdkmanager --uninstall build-tools;29.0.2--list_installed看当前 SDK 目录里实际装了哪些包比 GUI 里的勾选状态更可靠。--install可以绕过界面限制直接安装--uninstall用来清理残留版本。Dolphin 的 AGP 7.1 默认绑定 build-tools 30.0.3如果你 SDK 目录里同时存在多个 build-tools先看项目里的buildToolsVersion再删别把还在用的版本清了。4. 模拟器和真机设备接入Dolphin 里跑 App 的两种路径Dolphin 上跑 App 有模拟器和真机两条路。很多人卡在模拟器启动后黑屏或者真机连上后adb devices显示 unauthorized。这章把两条路的坑分开说。4.1 先判断 Mac 芯片类型和虚拟化方式模拟器起不来的原因大多是没有匹配正确的虚拟化后端。先看当前机器类型uname -m sysctl -n machdep.cpu.brand_stringuname -m输出arm64就是 Apple Silicon输出x86_64是 Intel。Dolphin 的模拟器内部是 qemu 虚拟机在 Intel 上使用 Intel HAXM 或 macOS 的 Hypervisor.Framework在 Apple Silicon 上使用 Hypervisor.Framework 跑 arm64 镜像。Dolphin 发布那会儿 Apple Silicon 模拟器还叫 Preview所以如果你用的是 M 芯片最好选 API 30 或 31 的arm64-v8a系统镜像不要为了兼容性去下 x86_64 镜像再开虚拟化那样反而更慢。4.2 命令行创建并启动 AVD在终端创建 AVD 比在 GUI 里点来点去更可控。先安装系统镜像sdkmanager system-images;android-30;google_apis;arm64-v8a镜像标识由三段组成android-30是 API 级别google_apis表示带 Google API 的系统镜像arm64-v8a是 CPU 架构。Intel Mac 上把arm64-v8a换成x86_64。创建 AVDavdmanager create avd -n dolphin_avd -k system-images;android-30;google_apis;arm64-v8a -d pixel_5-n dolphin_avd是给这个模拟器起的名字之后启动都要用这个名字-k指定系统镜像-d pixel_5是设备定义。avdmanager在cmdline-tools/latest/bin下和 sdkmanager 同级。如果提示unknown device先运行avdmanager list device查看设备 ID。启动模拟器emulator -avd dolphin_avd -no-snapshot -gpu host-no-snapshot是忽略上次的状态快照防止 Dolphin 加载旧快照后崩溃-gpu host走 macOS 的 GPU 渲染。如果远程桌面环境下黑屏把host换成swiftshader_indirect这是软件渲染慢但兼容性好。模拟器启动是否完成adb wait-for-device shell getprop sys.boot_completed这个命令会阻塞到设备上线然后输出1表示 boot 完成。如果一直没输出大概率是镜像架构选错了或 GPU 参数不对。4.3 连接小米手机等 Android 真机小米手机连接 mac 的坑通常在手机端。先打开开发者选项设置 我的设备 全部参数与信息连点MIUI 版本7 次。返回后进入开发者选项打开USB 调试。这里有两个容易被忽略的项USB 安装和USB 调试安全设置。后者用于允许 adb 模拟点击和自动安装不打开的话adb install会报INSTALL_FAILED_USER_RESTRICTED。连接后依次执行adb devices adb shell getprop ro.product.model adb install -r app-debug.apkadb devices能看到设备状态device表示正常unauthorized表示手机上没点允许调试弹窗offline多半是线材或 USB 端口问题。adb shell getprop ro.product.model用来确认设备已被正确识别。adb install -r里的-r是覆盖安装适合不断调试的场景。不想用数据线的话Android 11 以上支持无线调试adb pair 192.168.1.23:41347 adb connect 192.168.1.23:44559adb pair需要手机开发者选项里无线调试页面给出的配对码和端口adb connect使用的是配对成功后显示的连接端口。手机和 mac 要在同一局域网内mac 睡眠后 adb 会掉线重新 connect 一次即可。4.4 模拟器连接不上的快速恢复模拟器窗口出现但adb devices里没有先查模拟器端口是否被占用lsof -iTCP:5554 -sTCP:LISTEN adb kill-server adb start-server5554 是第一个 AVD 的控制台端口。被占用时adb不会自动扫描到新设备。adb kill-server加adb start-server是最常用的恢复手段不会影响已连接的真机只会重新启动本机的 adb 服务。5. 老项目迁移与三个高发问题SDK 无法勾选、sync 慢、tag number 报错从 2020 年之前的老项目切到 Dolphin 时常被三个现象卡住界面里 SDK 勾不了、Gradle Sync 永远在转圈、构建期出现 “tag number over 30 is not supported” 这种冷门报错。下面按处理频率排一下。5.1 SDK 无法勾选的三种绕过方式SDK Manager 勾选失效多发生在 mac 上磁盘权限正常但 Studio 内嵌的安装器检测不到目标目录的情况。第一在Android SDK面板右下角勾选Show Package Details逐项展开看当前已安装的 Platform 和 Build Tools。如果显示 Installed 但项目里找不到说明目录损坏勾选对应版本再点 Apply 重装。第二如果目标版本灰色不可点击直接用命令行装sdkmanager --list | grep platforms;android-31 sdkmanager platforms;android-31第三如果项目是compileSdkVersion 28不需要在 SDK Manager 里找新版本覆盖直接命令行安装对应包即可。需要注意不要在同一 SDK 目录里混合多个 commandline-tools 版本否则 Studio 解析 SDK 路径时会出现“SDK location not found”。5.2 Gradle Sync 卡在 “Importing Gradle Project” 的典型处理Sync 慢主要来自两个网络请求下载 Gradle 发行版和下载依赖。前者看gradle-wrapper.properties后者看第 3 章的init.gradle。但有两个细节常被忽略。第一项目里同时存在settings.gradle和settings.gradle.kts时Dolphin 会优先使用.kts导致你在.gradle里配置的仓库没有生效。检查项目根目录删掉多余的那个保留实际在用的格式。第二老项目里经常会写classpath com.android.tools.build:gradle:3.6.0这个 AGP 版本在 Dolphin 上会提示 unsupported。把 AGP 提到 7.1.xGradle 提到 7.2 以上即可。注意 Gradle 仓库里的版本号形如7.4.2-bin.zip不要写7.4.2-all.zip因为 Dolphin 插件默认只认 bin 分发。5.3 build 时报 “tag number over 30 is not supported”这个报错字面意思很难理解常见触发场景是资源数量庞大或做过资源混淆的项目在 Dolphin 的 AAPT2 增量构建里资源索引超过内部状态上限。遇到后第一步不是改代码而是清空构建缓存./gradlew cleanBuildCache ./gradlew clean rm -rf app/buildcleanBuildCache清的是 Gradle 的 build cacheclean清的是项目中间产物rm -rf app/build是把 app 模块的生成目录彻底删掉。之后重新构建大多数情况下索引会重新生成错误不再出现。如果清理后仍复现检查项目里的buildToolsVersion。Dolphin 推荐 30.0.3低于 30.0.0 时资源链接器行为差异明显。项目里如果启用了shrinkResources或资源混淆插件临时关掉再编译能确认是否资源压缩阶段引发的索引错乱。android { buildToolsVersion 30.0.3 buildTypes { debug { shrinkResources false minifyEnabled false } } }shrinkResources false和minifyEnabled false会临时跳过资源裁剪和代码混淆定位问题后可以再打开。5.4 Android Studio 怎么设置中文Dolphin 可以通过插件直接汉化。进入Settings Plugins Marketplace搜索Chinese (Simplified) Language Pack安装后重启。该插件在 2021.3 分支上可用重启后菜单变中文但部分构建日志和异常堆栈保持英文属于正常现象。如果插件市场加载不出来先确保 mac 到dl.google.com的网络连通性正常再重试一次。6. 验证 Dolphin 是否跑在正确架构上一个 Mac 专属检查技巧在 Apple Silicon 上安装 Dolphin 后它实际上是以 Rosetta 2 转译方式运行的。虽然能用但大项目构建时会有额外开销。确认当前运行架构ps -p $(pgrep -f Android Studio.app) -o archps -p指定进程号pgrep -f模糊匹配包含Android Studio.app的进程-o arch只输出 CPU 架构列。如果看到x86_64说明 Dolphin 是 Intel 版本在转译执行如果你换了新版 Studio这里会显示arm64。Dolphin 本身没有包含 arm64 的二进制所以这个结果显示x86_64不是异常它只是提醒你转译在持续占用 CPU 和内存。6.1 用文件类型确认 binary 是否支持原生 arm64file /Applications/Android Studio.app/Contents/MacOS/studio输出里有executable x86_64时说明这个版本没有 arm64 slice。此时在 Finder 里勾不勾“使用 Rosetta 打开”都没有意义因为二进制本身就缺这一份只有更新到支持 Apple Silicon 的版本才能原生运行。6.2 转译开销大时的内存调整边界如果转译导致编译卡顿先调大 Studio 的 JVM 堆而不是急着换机器。编辑~/Library/Application Support/Google/AndroidStudio2021.3/studio.vmoptions-Xmx3072m -XX:MaxMetaspaceSize1024m-Xmx是 JVM 最大堆内存-XX:MaxMetaspaceSize是类元数据上限。Dolphin 默认只有 2GB 堆16GB 内存的 mac 上提到 3GB 是安全的8GB 内存机器不要超过 2GB否则模拟器没有余量。6.3 三个命令验证安装闭环配置完成后重启 Studio跑一次真实的编译和安装cd /path/to/project ./gradlew assembleDebug adb shell am start -n com.example.app/.MainActivityassembleDebug通过说明 JDK、Gradle、SDK 三个关键环境在 Dolphin 里已经对齐。adb shell am start能把应用拉起说明设备链路的端口、授权和调试权限都没问题。如果 autostart 报 Activity 找不到就把包名和 Activity 全限定名替换成自己项目的实际值。到这一步Dolphin 在 Mac 上的安装和验证才算完整收尾。本文还有配套的精品资源点击获取
.Ext系列文件系统)
