说实话后台收到的搜索词里“dart sdk下载”这种词我见得太多了。每次看到有人还在满世界找链接我都觉得有必要把这一步的坑系统性地讲一遍。很多朋友并不是不会写 Dart 代码而是卡在最前面搜索引擎搜出来的结果是 Android SDK、是某个硬件厂商的二次开发 SDK、是各种“高速下载器”真正要的 Dart SDK 反而要翻好几页才看得到。这篇文章就是替你把下载、安装、验证、排错这一整条链路捋清楚。无论你是第一次接触 Dart还是已经写了几年 Flutter 但第一次想在纯命令行环境下用 Dart都适用。我会尽量用大白话讲把“为什么这么做”也交代清楚而不是丢给你一个链接就完事。1. 先分清你需要的到底是哪个“Dart SDK”1.1 搜索引擎里那一堆“SDK 下载”大部分不是你要的如果你跟我一样第一次搜“dart sdk下载”大概率会被搜索结果弄得有点懵。第一屏往往是 Android SDK、Android Studio 的下载页、各种“SDK 管理器”教程、某个国产相机的二次开发 SDK甚至还有一堆像模像样的“下载器”。这些页面不能说完全无关但跟你想要的纯 Dart 开发环境基本是两码事。搜索引擎里“SDK”是一个很宽泛的词凡是“提供接口和工具让别人做二次开发的开发包”都能叫 SDK。你要找的是 Dart 语言官方的编译/运行工具链它负责把.dart文件跑起来、把依赖拉下来、把代码编译成可执行文件。而 Android SDK 是给安卓应用开发用的工业相机 SDK 是给硬件二次开发用的Vivado SDK 是给 FPGA 工程用的。它们和 Dart SDK 没有任何替代关系搜索时看到这些结果直接跳过就行。1.2 Dart SDK 与 Flutter 内置 Dart 的关系另一个高频误会是“我装了 Flutter是不是就不用单独下载 Dart SDK了”答案是如果你只想开发 Flutter 应用确实可以不用但如果你还想在命令行里写普通 Dart 脚本或者跑dart format、dart analyze、dart pub这类命令那最好还是单独装一份。Flutter SDK 自己会带一个 Dart SDK位置在 Flutter 安装目录下的bin/cache/dart-sdk。平时你运行 Flutter 命令时内部会调度这套内置 Dart。问题是这个内置版本是跟着 Flutter 版本走的Flutter 升级后它也会变你没法单独控制它。如果你只依赖它命令行里就不会有全局dart命令除非你手动把bin/cache/dart-sdk/bin加入 PATH但这样又有可能和以后装的独立 Dart 冲突。我的建议很直接只在 Flutter 项目里写界面用 Flutter 自带 Dart不手动下载减少版本干扰。需要写独立脚本、命令行工具、服务端程序或者想在全局随意敲dart命令单独下载 Dart SDK同时避免把 Flutter 内置 dart 目录写进 PATH。这两种方式并不矛盾关键是版本要统一不然项目里pubspec.yaml声明的 sdk 范围可能和全局dart命令不一致后面会出各种诡异的报错。1.3 什么时候才真的需要单独下载 Dart SDK除了上面说的普通 Dart 项目还有几类场景绕不开单装 Dart SDK。第一类是 CI/CD 服务器上跑构建任务你不可能为每台构建机都装个完整 FlutterDart SDK 小得多。第二类是写纯 Dart 的 CLI 工具比如基于dart pub global activate安装一些命令行包没有全局 dart 命令就不方便。第三类是使用 dart-sass、用 Dart 写后端服务、或者做 MAVLink 无人机通信脚本这类不涉及 UI 的工作。我见过不少朋友一开始只装了 Flutter结果在终端里敲dart pub get直接提示找不到命令才意识到自己少了一个独立 SDK。所以如果你已经知道自己要在非 Flutter 环境下使用 Dart 语法那下载 Dart SDK 就是绕不开的第一步。2. 官方下载渠道与压缩包选择一份能直接照着抄的清单2.1 官方下载页的正确入口Dart 的官网是 dart.dev进入后找到 Get Dart 页面或者直接访问 dart.dev/get-dart。那里会提供不同操作系统的下载入口尽量从这里进不要从第三方转载站进。官方页面通常提供两种形式一种是压缩包Windows 上是 zipLinux/macOS 上也是 zip另一种是 Windows 下的可执行安装包。网页会自动识别你的操作系统但平台选择也可能需要手动切换。下载前确认几个信息版本渠道stable 还是 beta操作系统Windows、macOS 还是 Linux架构x64、arm64、IA32老旧机器下载方式SDK 压缩包或者安装器官方压缩包的实际下载地址通常挂在对象存储上看起来是一长串 URL文件名类似dartsdk-windows-x64-release.zip。这个文件名里其实已经把关键信息都写清楚了中间是操作系统和架构后面是发布渠道。只要你懂这一串拿到任何镜像也不会懵。2.2 stable、beta、dev 怎么选Dart SDK 的发布渠道分为 stable 和 beta早期还有 dev 渠道。稳定版就是普通开发者和生产环境使用的更新节奏较慢兼容性有保障beta 是下一版本的功能预览会引入新 API也可能有一些还没修完的边界问题dev 是最新的开发中版本主要给大胆试新的开发者用。这里直接用表格对比会比较清楚渠道稳定性新特性适合场景stable最高最新特性要等稳定版发布绝大多数项目、生产环境、学习使用beta中等能看到下一版大部分新功能提前适配新 API、参与新特性调研dev较低每天/每周都有变化核心库开发、研究前沿行为我的建议非常保守99% 的人直接选 stable不要因为看到下载页上有 beta 就觉得“Beta 是不是更好”。对新手来说一个刚发布的 beta 版本里很可能藏着 API 变化网上教程写的是旧 API你装完发现代码跑不通还要怀疑是自己配置有问题。除非你明确知道自己在做什么否则稳定版永远是对的。2.3 为什么我坚持用 zip/tar.gz 而不是安装包在 Windows 上Dart 官方也提供 exe/msi 安装包双击就能装。但我个人更推荐直接下载 zip 解压到某个目录里理由有三条。第一zip 是绿色的卸载时删目录就行不会在注册表里留下依赖垃圾安装包虽然方便但升级和卸载都更重。第二SDK 更新迭代很快我用 zip 可以同时保留好几个版本切版本时只需要改 PATH 指向不用反复跑卸载向导。第三在 CI 环境或者远程服务器上解压 zip 比静默安装一个 msi 要更容易脚本化出错概率也更低。zip 方式的缺点只有一个就是 PATH 环境变量要自己配置但后面我会把这一步拆开讲照着做五分钟就能搞定不怕。3. 三个平台上的落地安装路径、环境变量与验证3.1 Windows解压即用但 PATH 要设置对Windows 下载 zip 之后解压出来会得到一个dart-sdk文件夹。不要把这个文件夹直接扔在“下载”目录里建议放到一个固定位置比如D:\dev\dart-sdk。为什么要固定因为 PATH 里记录的是绝对路径一旦你以后清理下载目录或移动文件夹终端里的dart命令就会瞬间消失排查起来又得折腾半天。解压完成后按 Win 键搜索“环境变量”打开“编辑系统环境变量”在“用户变量”或“系统变量”里找到Path编辑并新增一条D:\dev\dart-sdk\bin注意是dart-sdk\bin不是dart-sdk本身。bin目录里才是 dart.exe、dartaotruntime.exe 这些可执行文件。如果不带\bin系统是找不到命令的。改完环境变量后必须重新打开一个终端窗口环境变量才会重新读取。然后在 cmd 或 PowerShell 里敲dart --version如果输出Dart SDK version: 3.x.x (stable)之类的信息说明安装成功。如果提示“不是内部或外部命令”优先检查是不是\bin没加对或者终端没重开。3.2 macOS 的 Intel 与 Apple Silicon 注意事项macOS 上同样是下载 zip 解压然后丢到一个合适的目录比如~/development/dart-sdk。把解压出的dart-sdk文件夹放入这个目录后在~/.zshrc里加一行export PATH$PATH:$HOME/development/dart-sdk/bin然后执行source ~/.zshrc再用dart --version验证。这里特别要注意 CPU 架构。Apple Silicon 的 Mac 下载 arm64 版本的 Dart SDKIntel 的 Mac 下载 x64 版本。如果下反了也不是完全不能运行但转译层会拖慢启动速度有些二进制功能也可能异常。用uname -m先看一眼机器架构输出arm64就是 Apple Silicon输出x86_64就是 Intel然后再去下载页选对应包。还有一个 macOS 特有的小坑某些版本的 macOS 会校验从网络下载的应用包。如果解压后运行dart被 Gatekeeper 拦截右键点击可执行文件选择“打开”或者在“系统设置-隐私与安全性”里允许它运行即可。命令行工具被拦截的概率不高但遇到时要能反应过来别以为是 SDK 坏了。3.3 Linux 下的软链接与多版本管理Linux 下基本也是解压到/opt或者~/tools然后修改~/.bashrc或~/.zshrc里的 PATHexport PATH$PATH:/opt/dart-sdk/bin但很多 Linux 用户会遇到一个更头痛的问题系统里可能不止一个 Dart。有些包管理器会自己装一份比如用 apt 安装某些软件时会带上 dart-sdk 依赖于是/usr/lib/dart/bin/dart和/opt/dart-sdk/bin/dart同时存在。这种情况下PATH 里靠前面的目录会先被命中你根本不知道自己执行的是哪一个。解决办法是装完独立 SDK 之后用which dart看当前命中的路径。如果发现不是你想要的那一份可以把 PATH 顺序调一调或者直接建软链接统一入口sudo ln -s /opt/dart-sdk/bin/dart /usr/local/bin/dart这样相当于把/usr/local/bin/dart指向你指定的版本只要/usr/local/bin在 PATH 里就不会被包管理的旧版本干扰。软链接方案对服务器环境特别实用因为服务器上经常要保证根用户和普通用户看到的是同一个 Dart 版本。4. 装完之后第一件事让 dart 命令链完整可用4.1 用 dart --version 和 where/which 验证装完不是只敲个dart --version就完事了。我会习惯性地再跑几条命令确认工具链是完整的dart --version dart pub --version dart format --version这三条命令分别对应 SDK、包管理器、代码格式化器。如果某条命令报错通常说明 SDK 文件不完整或者 PATH 里混进了别的东西。接着查看 dart 命令的实际路径。Windows 上用where dartLinux/macOS 上用which dart。重点看结果是不是你解压的那个目录。我在实际排障中见过不少案例环境变量里同时加过 Flutter 内置 Dart 的 path 和独立 Dart 的 path结果dart命令被 Flutter 内置版抢了先项目里pubspec.yaml写的是要求 3.2但实际运行的却是 3.0报错信息非常不容易看懂。所以这个“最后谁胜出”一定要确认清楚。4.2 用 dart create 快速跑通一个新项目验证完命令我建议立刻创建一个最小项目确认整个链路真正能跑起来而不是只看到版本号就收工。在任意目录执行dart create -t console hello cd hello dart pub get dart rundart create -t console hello会生成一个命令行程序的骨架里面有bin/hello.dart和默认的pubspec.yaml。dart pub get会把依赖拉到本地的.dart_tool目录dart run则会直接执行入口函数控制台会打印 Hello World 之类的输出。如果这三步都通过你的 Dart SDK 下载安装就可以宣告成功。后续写独立脚本时直接在文件头部写void main() { print(hello dart); }然后dart run xxx.dart即可。这个流程比准备 Flutter 环境要快很多Dart SDK 本身不依赖 Android Studio 或 Xcode下载完就能写命令行工具。4.3 第一批依赖怎么拉dart pub get 与镜像配置很多人在搜“dart get”而不是“dart pub get”其实是因为印象里有个dart get命令。工具链演进到现在推荐写法是dart pub get旧版单独的pub get命令已经被逐渐整合进dart pub这个子命令体系里。所以终端里敲dart pub get才是从 pub.dev 拉取依赖的标准姿势。拉取依赖时如果你所在网络访问 pub.dev 不太稳定经常卡在Resolving dependencies...可以临时指定环境变量export PUB_HOSTED_URLhttps://pub.flutter-io.cn export FLUTTER_STORAGE_BASE_URLhttps://storage.flutter-io.cn然后重新执行dart pub get。注意这个配置只是影响 Dart 包的下载源不会改变 SDK 本身的行为。镜像有时会滞后一点如果某些包在镜像上不存在临时把环境变量清掉再拉一次就能定位是不是同步问题。这里插一句下载页可能还会让你关联到“Dart SDK 的 pdf 教程”之类的搜索结果。我不建议依赖那些来路不明的 PDF因为文档更新速度很难跟上 API 变化真正可靠的是 dart.dev 上的官方文档和使用dart doc生成的本地 API 文档。新手经常单独搜的dart future其实就是语言内置的异步 API装完 SDK 后打开dart:async库就能看。5. 下载和安装中我遇到的高频翻车现场5.1 下载了个寂寞文件损坏与校验和下载大文件最怕的就是断点续传没处理好zip 包下了个 99% 就结束解压时却报错。Dart SDK 压缩包通常有几百 MB网络稍不稳定就会出现这种情况。解压报错时不要反复重试“右键解压”。先做两件事第一删掉旧文件重新下载第二尽量用支持断点续传的下载工具或者浏览器内置的下载管理。下载完成后官方页面通常会给 SHA-256 校验值你可以算一下本地文件的校验和比对。Windows PowerShell 里算 SHA-256 的命令是Get-FileHash .\dartsdk-windows-x64-release.zip -Algorithm SHA256macOS/Linux 里用shasum -a 256 dartsdk-windows-x64-release.zip如果算出来的值和官方对不上说明文件在传输中已经损坏这种包哪怕能解压出几个目录运行起来也会莫名其妙崩。别心疼那点下载时间删了重来比排错快得多。5.2 命令找不到PATH 顺序和残留版本“dart 命令找不到”是我收到最多的提问。拆开来看大部分情况不是 SDK 没下好而是 PATH 没配好或者配置之后没重启终端。排查的第一件事是确认你修改的是哪个 PATH。Windows 上用户变量和系统变量是两套如果你改了用户变量但某些终端是以管理员身份打开并加载了系统变量顺序可能会导致新的 PATH 没被读到。macOS/Linux 上要确认你改的是当前 shell 的配置文件而不是另一个 shell 的。比如你在.bashrc里加了配置但当前终端用的是 zsh那当然不会生效。还有一类情况是机器里以前装过 FlutterFlutter 的bin/cache/dart-sdk/bin被人手动加进了 PATH。等独立 Dart SDK 装完两个入口同时存在系统先命中旧的那个于是一个“旧版本 dart”就一直在占用终端里dart这个名字。用where dart或which dart查一下发现路径不对直接清理 PATH 里的残留项就行。5.3 版本不匹配报错not found / not verified / requires SDK另一个常见报错是项目跑起来时提示“The current Dart SDK version is X, but the package requires SDK version Y”意思是你本机的 Dart 版本不在项目要求范围内。这种情况常见于项目刚克隆下来pubspec.yaml里写的环境要求很严你机器上的 Dart 走的是 Flutter 内置版、系统包管理版、独立版三者之一版本对不上。我的处理顺序如下先确认当前dart --version到底显示多少。看项目里pubspec.yaml的environment: sdk:区间。如果当前版本太低就升级独立 Dart SDK或者让 Flutter 升级到匹配的版本。如果项目需要特定旧版本就装多版本切换而不是硬改pubspec.yaml的区间。还有那种类似sdk version xxx not verified的报错往往是团队内部某些工具链把 SDK 版本号写死导致的不一定就是 Dart SDK 自己的问题。这种情况下我会去检查工具配置文件里的 SDK 版本声明把它改成当前可用版而不是怀疑 SDK 下载源有毛病。5.4 中文路径、空格路径、杀毒软件误删 bin最后一批问题往往跟解压位置有关。如果解压路径里有中文目录比如D:\下载\开发包\dart-sdk部分终端模拟器和构建脚本对 UTF-8 路径处理不彻底会出现命令能执行但找不到资源文件的诡异问题。macOS 和 Linux 上类似路径里的空格也需要转义虽然大多数时候没问题但能避开就避开。更烦的是杀毒软件。Dart SDK 里的 dart.exe 本身是正常二进制但有些杀毒软件会对“能从网络下载代码并执行”的开发工具高度敏感偶尔会误报并直接隔离dart.exe。装完用where dart能找到路径但一运行就被杀掉或者在项目目录里生成一堆隔离记录基本就是杀毒软件搞的。我的应对方法是把解压目录加入杀毒软件的白名单如果公司有统一安全管理中心让同事把 Dart SDK 目录加到例外列表。不要为了运行 SDK 关掉整个杀毒软件那样风险更大。6. 版本升级、多版本共存与后续工具链补全6.1 升级 Dart SDK 的正确节奏Dart SDK 的升级不是“点一下更新”就行的。如果你是 zip 安装方式升级通常就是下载新版本压缩包解压后覆盖到原目录或者换一个新目录改 PATH。覆盖前最好先把旧的bin目录里的文件清掉再解压避免新旧文件混在一起。但更稳妥的做法是按项目走每个项目在pubspec.yaml里都会声明environment.sdk依赖的解析也是基于这个约束。全局 SDK 换来换去项目只要在允许范围内就能跑所以升级前先看一眼项目约束别一股脑把全局版本拉到最新结果老项目突然报出一堆弃用 API 的警告。平时我会保持稳定版跟随最新版本号但不会追 beta。觉得某个新特性很有用而想提前试用时我会单独装一个 beta 目录并用下面的“多版本切换”方式隔离不让 beta 污染日常环境。6.2 多版本切换ASDF、FVM 和手动改 PATH如果你同时维护多个项目有的要老版本有的要新版本只靠一个全局 PATH 肯定不够。常见方案有三种。第一种是 ASDF一个通用的多运行时版本管理器asdf plugin add dart asdf install dart 3.2.0 asdf local dart 3.2.0asdf local会在当前目录生成.tool-versions文件进入此目录时自动切换到 3.2.0其他目录用全局版本。它适合在 Linux/macOS 上使用Windows 用户支持相对弱一些。第二种是 FVM主要在 Flutter 项目里用但它管理的其实是 Flutter 版本顺带会带出对应的 Dart 版本。因为 Flutter 内置 Dart 版本与 Flutter 版本强绑定你只需要记住 FVM 切 FlutterDart 会跟着走。第三种是最朴素的下载多个版本的 zip目录按D:\dart-sdk-3.2\、D:\dart-sdk-3.5\分开需要哪个就把哪个的bin放到 PATH 最前面。这个方案看起来土但对 CI 和临时环境是最可控的我自己的服务器上就一直留着两三个版本的目录。6.3 顺手补全工具链dart-sass、dart compile 和脚本开发下载 Dart SDK 不只能写 Dart 脚本。很多流行工具本身就是用 Dart 写的最常见的例子是 dart-sass。只要全局 Dart 命令可用你可以一条命令把它装到全局dart pub global activate sass之后sass --version就可以在任意目录使用。这类通过dart pub global activate安装的 CLI 工具本质上就是借助 Dart SDK 的包管理和编译能力部署的所以 SDK 目录本身尽量别乱动否则全局工具全都会失效。此外dart compile exe可以直接把 Dart 脚本编译成单文件可执行程序dart compile exe bin/hello.dart -o hello编译后的程序不依赖 Dart SDK直接在目标机器上运行。这个能力特别适合配合 MAVLink、串口通信、服务端脚本等场景我之前处理过一个用 Dart 向无人机地面站协议发送航点信息的脚本就是先把脚本在本地跑通再用dart compile exe打成独立二进制丢到工控机上执行省去了一堆运行时安装步骤。6.4 我自己的最终检查清单最后分享一套我每次在新机器上装完 Dart SDK 都会过的检查清单照着走一遍基本不会漏从 dart.dev/get-dart 进入选 stable 渠道操作系统和架构确定无误。用 zip 解压到纯英文、无空格的固定目录。把SDK目录\bin加入 PATH修改后重新打开终端。dart --version、dart pub --version、dart format --version都正常。用where dart或which dart确认命中的不是 Flutter 内置版或系统残留版。dart create -t console hello dart pub get dart run全链路成功。校验过 SDK 压缩包的 SHA-256杀毒软件白名单已设置。只要这七点都通过Dart SDK 下载这件事就算是真正干完了剩下的大把时间应该花在写业务和调逻辑上而不是继续折腾环境。说白了下载 SDK 只是整个 Dart 开发流程里最无趣的一环配置好就别再反复动它。