用途
setup-local-sdk 用于指导用户把 .NET SDK 安装到项目本地的 .dotnet/ 目录，并借助 global.json 的 paths 特性（.NET 10+）完成接线。示例使用 .NET 11，但适用于任意版本（预览版或稳定版）。
得到的 SDK 完全隔离：不修改系统级 .NET 安装；从项目根目录执行 dotnet 命令时会被自动选中；删除 .dotnet/ 即可回退（rm -rf .dotnet/ 或 Remove-Item -Recurse -Force ..dotnet）。
不适用场景
- 用户需要系统级安装：应引导使用官方安装程序。
- 宿主 dotnet 低于 v10：paths 特性不存在，应说明并停止。
- 只需安装运行时：paths 仅作用于 SDK 解析。
输入与前置条件
输入项（Channel 或版本非必填，默认 11.0；Quality 默认 preview，可选 daily、preview、ga；jq 可选，用于 bash 团队脚本修补已有 global.json，缺失时不得覆盖该文件）。
前置条件：已全局安装 .NET 10+ SDK（dotnet --version 主版本 ≥ 10）；具备 curl（macOS/Linux）或 PowerShell（Windows）。
工作流程
- 明确要安装的 SDK 版本，映射为 --channel/--quality 或 --version 参数。
- 检查宿主版本：dotnet --version 主版本 < 10 时，在下载前停止并提示先系统级安装 .NET 10+。若用户已提供本机版本输出，以其为准，不应用工作区版本覆盖。
- 检测操作系统：uname -s 成功（含 MINGW*、MSYS*、CYGWIN* 等 bash 环境）用 bash/dotnet-install.sh；失败（无 Git Bash 的原生 Windows）用 PowerShell/dotnet-install.ps1。
- 检查是否已有本地 SDK（test -d .dotnet 或 Test-Path ..dotnet），存在则询问更新还是跳过。
- 通过官方地址 https://dot.net/v1/dotnet-install.sh 与 https://dot.net/v1/dotnet-install.ps1 下载并执行安装脚本，指定 --install-dir .dotnet；精确版本用 --version / -Version 替代 channel/quality。
- 用 ./.dotnet/dotnet --version（Windows 为 ..dotnet\dotnet.exe --version）获取实际版本号，供 global.json 使用。
- 创建或更新 global.json，sdk 段包含 version、allowPrerelease、rollForward、paths 与 errorMessage：paths 为 [".dotnet", "$host$"]，本地优先、系统级兜底；最新预览或浮动特性带用 rollForward: "latestFeature"，精确版本用 "disable"；仅安装预览版 SDK 时设 allowPrerelease: true；errorMessage 仅在创建团队安装脚本时加入。已有 global.json 时先读取并备份（如 global.json.bak），保留 msbuild-sdks、tools 等既有属性，只增改 sdk 段。无需版本锁定时可用最小配置 {"sdk":{"paths":[".dotnet","$host$"]}}。
- 更新 .gitignore，确保包含 .dotnet/。
- 如用户要求，在 global.json 与 .gitignore 完成后安装工作负载，且必须使用本地二进制（./.dotnet/dotnet workload install <workload>），无需 sudo；用 ./.dotnet/dotnet workload list 验证。Linux 上不提供完整 maui 元工作负载，目标为 Android 时可用 maui-android 等受支持工作负载。
- 如用户提及团队、共享、CI、脚本等，创建 install-dotnet.sh 与 install-dotnet.ps1：脚本备份 global.json 并保留既有设置；bash 脚本在需修补已有 global.json 时使用 jq，jq 不可用则拒绝覆盖并打印需手动合并的设置。若 global.json 已锁定 sdk.version 且主要需求是团队脚本，应复用该版本并先更新 global.json，避免仅为获知版本而启动长时间下载。同时需要安装与脚本时，先创建脚本和配置再做长时间安装，以保证可复现环境。
- 运行 dotnet --version 验证解析结果应与本地安装版本一致；不一致时检查 global.json 位置、paths 内容、宿主版本是否 ≥ 10。
- 总结并说明清理方式：删除 .dotnet/、从 global.json 移除 paths/errorMessage、可选删除安装脚本；给出最终 sdk 配置值，以及工作负载命令与验证结果或具体阻塞原因。
常见问题
- paths 被忽略：宿主 dotnet < v10，需系统级安装 .NET 10+。
- 解析到错误的 SDK：上级目录存在 global.json，需向上检查。
- 队友遇到“SDK not found”：.dotnet/ 被 gitignore 且未运行安装脚本，可在 global.json 中使用 errorMessage。
- 工作负载缺失：误用系统 dotnet，应使用 ./.dotnet/dotnet workload install。
- dotnet app.dll 运行时错误：paths 仅用于 SDK 解析而非 apphost，应使用 dotnet run 或设置 DOTNET_ROOT。
限制
需要宿主 .NET 10+ 才能使用 paths 特性；不改变系统级安装；paths 只影响 SDK 解析，不影响应用运行时。具体收费、平台支持范围与更多细节资料暂未提供。