Flutter零基础保姆级教学：Dart SDK安装与环境变量配置全流程-育师

1. 为什么零基础第一步要先把 Dart SDK 装明白

很多人第一次接触 Flutter，第一反应是去官网下载 Flutter SDK，结果解压完敲flutter doctor一堆红叉，回头才发现底层依赖的 Dart 根本没配好。Dart SDK 是 Flutter 的“发动机”，Flutter 的编译、热重载、代码分析全靠它。你可以把 Flutter 理解成一套装修好的房子，Dart SDK 就是地基和水电，地基没打牢，后面写多少 Widget 都是白搭。

这篇面向完全没碰过命令行的朋友，把 Windows 和 macOS 两条路都走一遍：从下载 Dart SDK、选安装路径，到配置 PATH 环境变量，再到用dart --version验证，最后演示配置失败时怎么一步步排查。全程命令可以直接复制，配置片段可以直接粘贴。适合谁？适合刚决定学 Flutter、电脑上还没装任何 Dart 相关工具、看到“环境变量”四个字就头大的新手。

先说一个容易踩的坑：Dart SDK 和 Flutter SDK 是两套东西。Flutter SDK 里自带了一份 Dart，但如果你先单独装 Dart SDK 来练语法、跑命令行脚本，环境会更干净，出问题也更好定位。等 Dart 跑通了，再上 Flutter，flutter doctor的报错会少一大半。所以这一节的目标很明确——让dart --version在任何目录下都能输出正常版本号。

安装路径选择上有个原则：路径里不要有中文、不要有空格。Windows 默认的C:\Program Files带空格，某些老版本工具链解析 PATH 时会出问题，建议统一放到C:\dev\dart-sdk这类纯英文短路径。macOS 则推荐放在用户目录下，比如~/development/dart-sdk，避免动系统目录还要 sudo。记住这个原则，后面所有配置都围绕它展开。

2. TaoToken 前置准备：把模型能力接进你的开发流

环境配好只是第一步，真正写 Flutter 的时候你会频繁需要查 API、生成样板代码、解释报错。这时候如果有个稳定的模型入口，效率会完全不一样。我习惯在动手配环境之前，先把 TaoToken 的 API Key 拿到手，这样后面写 Dart 脚本、调试 Flutter 时随时能调用模型对话。

TaoToken 官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，注册后在控制台创建 API Key。控制台地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，API Key 管理页在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。拿到 Key 之后先别急着写代码，把它存到环境变量里，别硬编码进源码。

这里要区分两个概念：Dart SDK 的 PATH 是给系统找dart命令用的；TaoToken 的 Key 是给模型请求做鉴权用的。两者互不干扰，但都建议用环境变量管理。Windows 下可以用系统属性里的环境变量面板，macOS 下写进~/.zshrc。下面给一个跨平台通用的存放思路：

# macOS / Linux，写入 ~/.zshrc 或 ~/.bashrc export TAOTOKEN_API_KEY="sk-你的key" export TAOTOKEN_BASE_URL="https://taotoken.net/api"

# Windows PowerShell，临时会话生效 $env:TAOTOKEN_API_KEY="sk-你的key" $env:TAOTOKEN_BASE_URL="https://taotoken.net/api"

注意 Base URL 用https://taotoken.net/api，不要加多余的斜杠或路径。如果你后面要接 Claude Code 这类编码工具，模型对话入口在 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite ，接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。长期做 Flutter 项目、需要 Agent 辅助的，可以看 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。

为什么要在装 Dart 之前提这个？因为很多新手配完环境就卡在“接下来干嘛”，有个模型入口能随时问“这段 Dart 报错什么意思”，学习曲线会平缓很多。前置准备做完，我们进入正题。

3. 可复制配置：Windows 与 macOS 的 Dart SDK 安装与环境变量

这一节是全文核心，两条系统分开写，配置片段直接抄。

3.1 Windows 安装 Dart SDK 并配置 PATH

先去 Dart 官方归档页下载稳定版 zip，选dart-sdk-windows-x64.zip。下载完解压，把整个dart-sdk文件夹放到C:\dev\dart-sdk，确保C:\dev\dart-sdk\bin\dart.exe这个路径真实存在。注意是解压后的dart-sdk目录，不是外面再套一层。

接下来配 PATH。图形界面操作：Win 键搜索“环境变量” → 编辑系统环境变量 → 环境变量 → 在“用户变量”里找到 Path → 编辑 → 新建 → 填入C:\dev\dart-sdk\bin→ 一路确定。命令行方式（管理员 PowerShell）也可以：

[Environment]::SetEnvironmentVariable( "Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";C:\dev\dart-sdk\bin", "User" )

配完必须重开终端，旧终端读不到新 PATH。然后验证：

dart --version

正常输出类似Dart SDK version: 3.x.x (stable)。如果提示'dart' 不是内部或外部命令，说明 PATH 没生效或路径写错，回到第 5 节排查。

3.2 macOS 安装 Dart SDK 并配置 PATH

macOS 推荐用 Homebrew，省去手动配 PATH 的麻烦：

brew tap dart-lang/dart brew install dart

装完which dart应该指向/opt/homebrew/bin/dart（Apple Silicon）或/usr/local/bin/dart（Intel）。如果你不想用 brew，手动下载 zip 解压到~/development/dart-sdk，然后编辑~/.zshrc：

export PATH="$HOME/development/dart-sdk/bin:$PATH"

保存后执行source ~/.zshrc，再跑dart --version。macOS 从 Catalina 起默认 shell 是 zsh，别改错文件。如果你用的是 bash，对应改~/.bash_profile。

3.3 用 settings.json 固化编辑器配置

如果你用 VS Code 写 Dart，建议在项目.vscode/settings.json里固化 SDK 路径，避免多版本冲突：

{ "dart.sdkPath": "C:\\dev\\dart-sdk", "dart.flutterSdkPath": "C:\\dev\\flutter", "editor.formatOnSave": true }

macOS 对应改成：

{ "dart.sdkPath": "/Users/你的用户名/development/dart-sdk", "editor.formatOnSave": true }

这个文件路径和原文一致，放在项目根目录的.vscode文件夹下。配好后编辑器会自动识别 SDK，代码补全和格式化都能用。注意 JSON 里 Windows 路径的反斜杠要转义成双反斜杠。

4. 验证请求：dart --version 与第一个 Hello World

环境配完不能只看版本号，得跑一个真实程序确认整条链路通。先建个目录：

mkdir dart-demo && cd dart-demo

新建hello.dart：

void main() { print('Hello, Dart!'); var name = 'Flutter 新手'; print('你好，$name'); }

运行：

dart run hello.dart

看到Hello, Dart!和你好，Flutter 新手两行输出，说明 SDK、PATH、运行时全部正常。这里顺便说几个 Dart 语法注意点：文件以.dart结尾，入口是main方法，绝大多数语句以分号结尾，但{}后面通常不加分号。

再验证一下包管理能力，Dart 自带 pub：

dart pub --version

如果这个命令也正常，说明工具链完整。接下来可以试试用 TaoToken 的模型对话帮你解释代码，入口在 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite ，把上面那段代码贴进去问“这段 Dart 的空安全怎么写”，比翻文档快。

验证阶段还有一个隐藏检查：确认dart命令解析到的是你刚装的那份，而不是系统里残留的旧版本。Windows 用where dart，macOS 用which dart，输出路径应该和你配置的一致。如果指向了别的目录，说明 PATH 顺序有问题，把新路径挪到前面。

5. 本篇常见错排查：401、local proxy failed、reading choices 与 OAuth

配置过程最容易卡在几个典型报错上，逐个拆。

报错一：'dart' 不是内部或外部命令/command not found: dart这是 PATH 没配好。Windows 检查C:\dev\dart-sdk\bin是否真的加进了用户变量 Path，且终端已重开。macOS 检查~/.zshrc里的 export 语句有没有拼错，source有没有执行。用echo $PATH看输出里有没有你的 SDK bin 目录。

报错二：401 Unauthorized这个通常出现在你调用 TaoToken API 时，不是 Dart 本身的问题。原因一般是 API Key 没传、传错，或者环境变量没生效。检查TAOTOKEN_API_KEY是否写对，请求头里是不是Authorization: Bearer sk-xxx。Key 管理页在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，重新生成一个再试。

报错三：local proxy failed/connection refused本地网络层的问题，常见于请求 Base URL 写错或本地有拦截。确认 Base URL 是https://taotoken.net/api，不要写成http或带多余端口。如果你在 Dart 里用http包发请求，检查Uri.parse的地址是否完整。

报错四：reading choices相关解析错误这类报错多出现在模型返回流式数据、而你的 Dart 代码按整段 JSON 解析时。解决思路是确认响应格式，流式用Stream逐块读，非流式用jsonDecode。如果你用 Claude Code 接入，配置要写全三件套：Base URL、API Key、Model ID。Claude Code 的接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，ClaudeCodeAnthropic 专用入口在 https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claudecodeanthropic&utm_campaign=rewrite 。

报错五：OAuth 登录失败如果你用 Codex 或类似工具，auth.json里的字段要完整。典型结构如下：

{ "base_url": "https://taotoken.net/api", "api_key": "sk-你的key", "model": "claude-sonnet-4-5" }

三个字段缺一不可，base_url结尾不要带斜杠。OAuth 失败多半是回调地址或 token 过期，重新走一遍授权流程即可。

排查通用心法：先确认命令本身能不能跑（dart --version），再确认网络请求能不能通（curl一下 Base URL），最后才看业务代码。分层定位，别一上来就怀疑代码。

6. 把环境变成长期可用的开发底座

环境配好只是起点，真正决定效率的是你怎么用它。我的习惯是每装一个新工具，立刻写一个最小可运行示例，跑通再往下走。Dart 这边就是hello.dart，Flutter 那边就是flutter create出来的计数器。跑通了，心里就有底。

另一个实用技巧：把常用命令做成别名。macOS 在~/.zshrc里加alias dr='dart run'，Windows 可以用 PowerShell 的Set-Alias。日积月累省下的时间很可观。还有，Dart SDK 会持续更新，建议每隔一两个月跑一次dart pub upgrade和版本检查，别让工具链落后太多。

如果你打算长期做 Flutter 项目，把模型辅助接进日常流程会轻松很多。模型对话入口 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 适合随手问语法，接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 适合查配置细节，Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 适合需要 Agent 长期协作的场景。API Key 在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 管理，控制台在 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite 。

最后留一个我踩过的坑：有次配完 PATH 死活不生效，折腾半小时才发现是终端开了两个窗口，改的是系统变量但验证用的是旧会话。重开终端就好了。所以记住，改完环境变量，第一件事永远是关掉所有终端重开一个。这个习惯能帮你省下大量无谓的排查时间。