Aspire CLI 的 Nix 官方打包从 flake 安装到固定输出二进制包全解析【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire导读本文基于 Aspire 仓库中第一方 Nix 打包目录 eng/nix/README.md 展开完整讲解 Aspire CLI 的 Nix 分发方案它如何以固定输出二进制包fixed-output binary package的形式消费官方 GitHub Release 归档如何通过nix run、nix profile add、项目 flake 与 overlay 四种方式被使用以及版本清单versions.json在稳定版发布流水线中是如何被自动或手动更新的。读完本文你将掌握在 NixOS 与 macOSdarwin上安装 Aspire CLI 的全部姿势、底层 derivation 的构建细节以及仓库侧维护 Nix 清单的完整发布契约。一、设计定位不编译源码只搬运官方归档eng/nix/目录存放的是 Aspire 官方维护的 Nix 打包first-party packaging其核心设计原则在 eng/nix/README.md 中说得非常明确二进制包而非源码包derivation 通过fetchurl抓取当前系统对应的官方版本化 GitHub Release 归档按哈希固定pinned by hash解包完整归档内容并在包输出中写入 Nix 安装路由的 sidecar 文件不参与源码构建它不会从源码构建 Aspire 仓库也不依赖 .NET SDK、dotnet publish等构建链路。这意味着 Nix 用户拿到的aspire与官方发布归档完全同源同一份aspire-cli-rid-version.tar.gz只是被 Nix 以可复现、可回滚、可卸载的方式纳管。顶层 flake.nix 是这个打包的对外入口它读取 eng/nix/versions.json 中的清单manifest为每个受支持系统通过pkgs.callPackage ./eng/nix/package.nix构造aspire-cli包并同时暴露packages、apps、overlays、checks与formatter五组输出。二、四种使用方式从零配置到项目集成2.1 直接运行nix run最轻量的用法是直接运行 CLI无需任何配置nix run github:microsoft/aspire#aspire-cli对应 flake 中的apps输出——flake.nix为每个系统注册了apps.aspire-cliprogram 指向${self.packages.${system}.aspire-cli}/bin/aspire并将apps.default指向同一程序。因此nix run无需 clone 仓库即可在当前 shell 中临时获得一个可用的aspire。2.2 永久安装nix profile addnix profile add github:microsoft/aspire#aspire-cli这会把aspire-cli装入当前用户的 Nix profile二进制进入 PATH之后可以直接敲aspire命令使用且与 Nix profile 的升级/回滚机制天然集成。2.3 在项目 flake 中引用推荐做法README 推荐在项目 flake 中让 Aspire 的nixpkgs输入跟随项目自己钉住的nixpkgs{ inputs { nixpkgs.url github:NixOS/nixpkgs/your-pinned-branch-or-rev; aspire.url github:microsoft/aspire; aspire.inputs.nixpkgs.follows nixpkgs; }; outputs { nixpkgs, aspire, ... }: let system x86_64-linux; pkgs nixpkgs.legacyPackages.${system}; in { devShells.${system}.default pkgs.mkShell { packages [ aspire.packages.${system}.aspire-cli ]; }; }; }这里有两个值得注意的版本控制点nixpkgs输入控制用于求值 derivation 的 Nix 包集合如stdenv、fetchurl、makeWrapper、icu、openssl、zlib等依赖版本Aspire CLI 版本由aspire输入自身的 revision 以及 eng/nix/versions.json 中钉住的版本决定。通过aspire.inputs.nixpkgs.follows nixpkgs两个 flake 共享同一个nixpkgs避免重复下载与潜在的依赖不一致。2.4 通过 overlay 注入pkgs.aspire-cli如果你更习惯 overlay 风格例如在自己的 configuration.nix 或 flake 中统一管理 overlay可以这样使用{ inputs { nixpkgs.url github:NixOS/nixpkgs/your-pinned-branch-or-rev; aspire.url github:microsoft/aspire; aspire.inputs.nixpkgs.follows nixpkgs; }; outputs { nixpkgs, aspire, ... }: let system x86_64-linux; pkgs import nixpkgs { inherit system; overlays [ aspire.overlays.default ]; }; in { devShells.${system}.default pkgs.mkShell { packages [ pkgs.aspire-cli ]; }; }; }overlay 的实现位于 flake.nix 的overlays.default它向final包集合注入aspire-cli final.callPackage ./eng/nix/package.nix { inherit manifest; }因此注入后你就可以像使用任何 nixpkgs 包一样使用pkgs.aspire-cli。三、支持的系统与 RID 映射Aspire CLI 的发布归档按运行时标识符RID命名Nix 侧则按自己的系统名消费。两者的一一映射关系来自 eng/nix/README.md 与 update-versions.sh 中的systems数组Nix systemAspire CLI runtime identifierx86_64-linuxlinux-x64aarch64-linuxlinux-arm64x86_64-darwinosx-x64aarch64-darwinosx-arm64该清单固定维护在 update-versions.sh 中顺序即versions.json的写入顺序保证重复运行产生最小 diff并由versions.json中的systems字段驱动flake.nix的supportedSystems——即只有清单里存在的系统才会被生成packages/apps/checks输出。对于不支持的平台package.nix 会在求值期直接抛错Aspire CLI does not publish a Nix package for system system.见entry manifest.systems.${system} or (throw ...)的逻辑。四、derivation 深度拆解固定输出二进制包如何组装package.nix 是整个打包的核心值得逐段拆解。4.1 输入与参数{ lib, stdenv, fetchurl, makeWrapper, autoPatchelfHook ? null, icu, openssl, zlib, manifest ? builtins.fromJSON (builtins.readFile ./versions.json), }:manifest默认直接读取同目录的versions.json也可由 flake/overlay 显式传入flake.nix就是通过callPackage显式inherit manifest传入的保证 flake 与包定义共享同一份数据Linux 侧需要icu、openssl、zlib以及stdenv.cc.cc.lib用于给原生二进制提供动态库依赖autoPatchelfHook用于自动修补 ELF 的 RPATH。4.2 系统分发与依赖装配system stdenv.hostPlatform.system; entry manifest.systems.${system} or (throw Aspire CLI does not publish a Nix package for system ${system}.); isLinux stdenv.hostPlatform.isLinux; linuxLibraries [ icu openssl zlib stdenv.cc.cc.lib ]; linuxLibraryPath lib.makeLibraryPath linuxLibraries;从清单中取出当前系统的entry含rid、archiveName、url、hash仅在 Linux 上引入autoPatchelfHook与动态库依赖darwin 平台依赖系统自带库不需要这些输入。4.3 固定输出的源码抓取src fetchurl { inherit (entry) url hash; };这是固定输出fixed-output的关键url指向版本化的releases/download/vversion/aspire-cli-rid-version.tar.gzhash为对应的 Nix SRI 哈希sha512-...形式。Nix 会校验下载内容与哈希完全一致一旦上游变更即失效从而保证可复现性。同时注意url 字段永远是公开的版本化 release 下载地址见 README 与脚本注释而不是可变的aka.ms渠道重定向——这保证了固定输出 fetch 的确定性。4.4 构建阶段纯搬运 包装sourceRoot .; nativeBuildInputs [ makeWrapper ] lib.optionals isLinux [ autoPatchelfHook ]; buildInputs lib.optionals isLinux linuxLibraries; dontConfigure true; dontBuild true; dontStrip true; installPhase runHook preInstall mkdir -p $out/lib/aspire-cli $out/bin cp -R . $out/lib/aspire-cli/ chmod 755 $out/lib/aspire-cli/aspire printf %s\n {source:nix} $out/lib/aspire-cli/.aspire-install.json makeWrapper $out/lib/aspire-cli/aspire $out/bin/aspire ${lib.optionalString isLinux --prefix LD_LIBRARY_PATH : ${linuxLibraryPath}} runHook postInstall ;这一步揭示了包内的最终布局完整归档原样保留Release 归档已经包含完整的 CLI 包自包含的 .NET 原生二进制因此dontConfigure/dontBuild/dontStrip全部置真只做解包搬运二进制与 sidecar 同目录存放真实二进制放在$out/lib/aspire-cli/aspire旁边写入.aspire-install.json内容为{source:nix}对外包装$out/bin/aspire是由makeWrapper生成的用户入口在 Linux 上通过--prefix LD_LIBRARY_PATH注入icu、openssl、zlib、glibc的运行库路径autoPatchelfHook负责把 ELF 的依赖补到可解析状态。4.5 sidecarNix 在 Aspire 安装路由体系中的身份.aspire-install.json正是 Aspire CLI 的安装路由 sidecarinstall-route sidecar。在源码侧InstallSource.cs 定义了完整的安装来源枚举其中Nix对应的线格式wire string正是nix/// summaryNix package or flake install./summary Nix, // ... internal const string NixWire nix;CLI 在运行时通过读取二进制旁的.aspire-install.json的source字段判断自己是从哪种途径安装的script / pr / winget / brew / dotnet-tool / localhive / nix。这一身份在 docs/specs/install-routes.md 中有详细契约说明并直接影响 CLI 的自更新行为与数据目录选择Nix 安装被归类为只读包管理器路由包输出位于只读的 Nix store 中CLI 不应尝试写回二进制所在目录因此 Nix 路由回落到默认 Aspire home设置了ASPIRE_HOME时用该环境变量否则为$HOME/.aspire作为数据目录见 install-routes.md 中对nix的说明BundleService.ComputeDefaultExtractDir是布局选择的唯一事实来源布局是 sidecarsource值的纯函数未知source与已知只读路由如nix都回落到默认 Aspire home避免向二进制旁写入。4.6 包元数据passthru { inherit manifest; inherit (entry) archiveName rid; }; meta { description Command line tool for Aspire developers; homepage https://aspire.dev; changelog https://github.com/microsoft/aspire/releases/tag/${manifest.releaseTag}; license lib.licenses.mit; sourceProvenance with lib.sourceTypes; [ binaryNativeCode ]; platforms builtins.attrNames manifest.systems; mainProgram aspire; };passthru暴露manifest、archiveName、rid供外部消费meta中值得注意的两点sourceProvenance明确声明这是binaryNativeCode二进制原生代码包而非源码构建产物mainProgram aspire让nix run等工具能自动找到可执行入口。五、版本清单versions.json固定哈希的数据源versions.json 是 flake 的真相文件当前示例仓库现状为版本13.4.6、release tagv13.4.6包含四个系统的条目。每个条目形如x86_64-linux: { rid: linux-x64, archiveName: aspire-cli-linux-x64-13.4.6.tar.gz, url: https://github.com/microsoft/aspire/releases/download/v13.4.6/aspire-cli-linux-x64-13.4.6.tar.gz, hash: sha512-kYL/Wsf5TjmZRkAScf0dyxAfwp4MiZm2COlH9wI1TTCwnbTes6dunDqx3OBMc2eEe4or50PFjnqjpD5CIw8IRQ }version/releaseTag稳定版号与其对应的v前缀 tagrid归档的运行时标识符archiveName归档文件名遵循aspire-cli-rid-version.tar.gz约定url不可变的版本化下载地址GitHub immutable releasehashNix SRI 格式sha512-base64的固定输出哈希。由于flake.nix通过builtins.fromJSON (builtins.readFile ./eng/nix/versions.json)读取清单修改这个文件即修改 flake 的分发内容——这也是下文版本更新机制的核心对象。六、版本更新机制自动流水线与手动脚本双通道6.1 自动通道随稳定版发布联动README 描述的更新链路为细节可交叉印证 docs/release-process.md 与 docs/ci/native-cli-packaging.md稳定版发布时release-publish-nugetAzure DevOps 流水线派发.github/workflows/update-nix-cli-flake.yml流水线从签名源码构建的BlobArtifacts中读取aspire-cli-*.tar.gz.sha512校验和也就是它校验并上传到 release 的同一批构件作为输入传给 workflowworkflow 据此构建清单——清单基于构建产物而非 GitHub Release这样在 release 仍是未发布的draft时就能生成清单GitHub 不可变 release 的约束draft 资产不会通过公开的releases/download/...URL 提供workflow 将 Nix 清单变更提交到release-github-tasks.yml创建的update-baseline-version分支并创建/更新基线 PR使发布后的稳定版更新聚合在一起。合并基线 PR 就是仓库内 Nix 的 ship 步骤它把main上的 flake 元数据更新为指向 GitHub release 资产与哈希url字段始终是公开的版本化下载 URL发布管理员把 draft 转为正式发布后即生效。本仓库没有单独的 Nix registry 发布步骤。6.2 手动通道针对已发布版本对已经发布的稳定版可直接运行eng/nix/update-versions.sh --version stable-release-version脚本默认行为是下载每个官方.sha512校验和资产公开下载 URLcurl换算成 Nix SRI 哈希后重写versions.json。6.3 离线模式release 流水线的调用契约当发布流水线运行时它改用--sha512 ridhex参数直接传入四个平台的十六进制摘要完全不读 releaseeng/nix/update-versions.sh --version 13.4.6 \ --sha512 osx-arm64hex \ --sha512 osx-x64hex \ --sha512 linux-arm64hex \ --sha512 linux-x64hex脚本头注释明确说明了这一离线契约。脚本实现中有几个值得注意的工程细节离线模式强约束只要传入任意一个--sha512就进入离线模式且四个平台必须全部提供sha512_override_for逐 RID 查找缺失即报错不允许混用部分传入 部分 curl保证结果可复现版本校验只接受稳定版x.y.z去掉前导v/V后匹配^[0-9]\.[0-9]\.[0-9]$prerelease/daily 渠道有意不写入——因为 Nix 固定输出 fetch 必须保证消费者钉住仓库后仍可复现校验和解析.sha512资产可能是纯 hex 或hex 文件名两列格式脚本只取第一 tokenread -r checksum _hex → SRI 转换hex_sha512_to_sri先规范化大小写与空白兼容 Windows/Unix 换行校验必须是 128 位 hex再用xxd -r -p | base64输出sha512-base64格式原子写入先写versions.json.tmp兄弟文件四个平台全部解析、哈希成功后才mv覆盖正式清单curl/哈希失败不会留下半成品bash 3.2 兼容sha512_override_for特意不用关联数组sha512_override_for注释说明保证在 macOS 自带的旧 bash 上本地测试也能运行。无论自动还是手动清单始终使用版本化 GitHub release URL而非可变的aka.ms渠道重定向确保 Nix 固定输出 fetch 的可复现性。七、与上游 nixpkgs 的关系README 明确说明本 flake 是仓库内的第一方包而上游NixOS/nixpkgs中的 derivation 可以复用相同的 release 资产 URL 形态、RID 映射与nix安装路由 sidecar 行为从而在 nixpkgs 中提供pkgs.aspire-cli体验。也就是说本仓库的打包定义了标准形态归档命名、哈希、sidecar、布局上游 nixpkgs 包与该形态保持一致即可让用户通过普通 nixpkgs 渠道安装二者面向同一份官方 release 资产来源一致、行为一致。八、实践小结与适用前提场景推荐方式命令/配置临时体验nix runnix run github:microsoft/aspire#aspire-cli本机常驻nix profile addnix profile add github:microsoft/aspire#aspire-cli项目 devShell 集成跟随式 flake input见 2.3 节示例统一 overlay 管理aspire.overlays.default见 2.4 节示例手动升级已发布版本update-versions.sheng/nix/update-versions.sh --version 稳定版发布流水线离线升级--sha512离线模式见 6.3 节适用前提与限制仅支持四个平台见第三节映射表其余系统在求值期直接抛错只跟踪稳定版x.y.zpreview/daily 渠道不会进入versions.json安装后属于只读包管理器路由CLI 数据落到默认 Aspire homeASPIRE_HOME或$HOME/.aspire不会修改 store 内的二进制该打包消费官方 release 二进制归档不在 Nix 侧从源码构建 Aspire 仓库。延伸阅读安装路由 sidecar 的完整契约见 docs/specs/install-routes.mdNix 打包在发布流程中的位置见 docs/release-process.md原生 CLI 打包与签名相关细节见 docs/ci/native-cli-packaging.mdsidecar 的读写与原子更新实现见 src/Aspire.Cli/Acquisition/InstallSidecarWriter.cs 与 src/Aspire.Cli/Acquisition/InstallSidecarReader.cs。【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Aspire CLI 的 Nix 官方打包：从 flake 安装到固定输出二进制包全解析
Aspire CLI 的 Nix 官方打包从 flake 安装到固定输出二进制包全解析【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire导读本文基于 Aspire 仓库中第一方 Nix 打包目录 eng/nix/README.md 展开完整讲解 Aspire CLI 的 Nix 分发方案它如何以固定输出二进制包fixed-output binary package的形式消费官方 GitHub Release 归档如何通过nix run、nix profile add、项目 flake 与 overlay 四种方式被使用以及版本清单versions.json在稳定版发布流水线中是如何被自动或手动更新的。读完本文你将掌握在 NixOS 与 macOSdarwin上安装 Aspire CLI 的全部姿势、底层 derivation 的构建细节以及仓库侧维护 Nix 清单的完整发布契约。一、设计定位不编译源码只搬运官方归档eng/nix/目录存放的是 Aspire 官方维护的 Nix 打包first-party packaging其核心设计原则在 eng/nix/README.md 中说得非常明确二进制包而非源码包derivation 通过fetchurl抓取当前系统对应的官方版本化 GitHub Release 归档按哈希固定pinned by hash解包完整归档内容并在包输出中写入 Nix 安装路由的 sidecar 文件不参与源码构建它不会从源码构建 Aspire 仓库也不依赖 .NET SDK、dotnet publish等构建链路。这意味着 Nix 用户拿到的aspire与官方发布归档完全同源同一份aspire-cli-rid-version.tar.gz只是被 Nix 以可复现、可回滚、可卸载的方式纳管。顶层 flake.nix 是这个打包的对外入口它读取 eng/nix/versions.json 中的清单manifest为每个受支持系统通过pkgs.callPackage ./eng/nix/package.nix构造aspire-cli包并同时暴露packages、apps、overlays、checks与formatter五组输出。二、四种使用方式从零配置到项目集成2.1 直接运行nix run最轻量的用法是直接运行 CLI无需任何配置nix run github:microsoft/aspire#aspire-cli对应 flake 中的apps输出——flake.nix为每个系统注册了apps.aspire-cliprogram 指向${self.packages.${system}.aspire-cli}/bin/aspire并将apps.default指向同一程序。因此nix run无需 clone 仓库即可在当前 shell 中临时获得一个可用的aspire。2.2 永久安装nix profile addnix profile add github:microsoft/aspire#aspire-cli这会把aspire-cli装入当前用户的 Nix profile二进制进入 PATH之后可以直接敲aspire命令使用且与 Nix profile 的升级/回滚机制天然集成。2.3 在项目 flake 中引用推荐做法README 推荐在项目 flake 中让 Aspire 的nixpkgs输入跟随项目自己钉住的nixpkgs{ inputs { nixpkgs.url github:NixOS/nixpkgs/your-pinned-branch-or-rev; aspire.url github:microsoft/aspire; aspire.inputs.nixpkgs.follows nixpkgs; }; outputs { nixpkgs, aspire, ... }: let system x86_64-linux; pkgs nixpkgs.legacyPackages.${system}; in { devShells.${system}.default pkgs.mkShell { packages [ aspire.packages.${system}.aspire-cli ]; }; }; }这里有两个值得注意的版本控制点nixpkgs输入控制用于求值 derivation 的 Nix 包集合如stdenv、fetchurl、makeWrapper、icu、openssl、zlib等依赖版本Aspire CLI 版本由aspire输入自身的 revision 以及 eng/nix/versions.json 中钉住的版本决定。通过aspire.inputs.nixpkgs.follows nixpkgs两个 flake 共享同一个nixpkgs避免重复下载与潜在的依赖不一致。2.4 通过 overlay 注入pkgs.aspire-cli如果你更习惯 overlay 风格例如在自己的 configuration.nix 或 flake 中统一管理 overlay可以这样使用{ inputs { nixpkgs.url github:NixOS/nixpkgs/your-pinned-branch-or-rev; aspire.url github:microsoft/aspire; aspire.inputs.nixpkgs.follows nixpkgs; }; outputs { nixpkgs, aspire, ... }: let system x86_64-linux; pkgs import nixpkgs { inherit system; overlays [ aspire.overlays.default ]; }; in { devShells.${system}.default pkgs.mkShell { packages [ pkgs.aspire-cli ]; }; }; }overlay 的实现位于 flake.nix 的overlays.default它向final包集合注入aspire-cli final.callPackage ./eng/nix/package.nix { inherit manifest; }因此注入后你就可以像使用任何 nixpkgs 包一样使用pkgs.aspire-cli。三、支持的系统与 RID 映射Aspire CLI 的发布归档按运行时标识符RID命名Nix 侧则按自己的系统名消费。两者的一一映射关系来自 eng/nix/README.md 与 update-versions.sh 中的systems数组Nix systemAspire CLI runtime identifierx86_64-linuxlinux-x64aarch64-linuxlinux-arm64x86_64-darwinosx-x64aarch64-darwinosx-arm64该清单固定维护在 update-versions.sh 中顺序即versions.json的写入顺序保证重复运行产生最小 diff并由versions.json中的systems字段驱动flake.nix的supportedSystems——即只有清单里存在的系统才会被生成packages/apps/checks输出。对于不支持的平台package.nix 会在求值期直接抛错Aspire CLI does not publish a Nix package for system system.见entry manifest.systems.${system} or (throw ...)的逻辑。四、derivation 深度拆解固定输出二进制包如何组装package.nix 是整个打包的核心值得逐段拆解。4.1 输入与参数{ lib, stdenv, fetchurl, makeWrapper, autoPatchelfHook ? null, icu, openssl, zlib, manifest ? builtins.fromJSON (builtins.readFile ./versions.json), }:manifest默认直接读取同目录的versions.json也可由 flake/overlay 显式传入flake.nix就是通过callPackage显式inherit manifest传入的保证 flake 与包定义共享同一份数据Linux 侧需要icu、openssl、zlib以及stdenv.cc.cc.lib用于给原生二进制提供动态库依赖autoPatchelfHook用于自动修补 ELF 的 RPATH。4.2 系统分发与依赖装配system stdenv.hostPlatform.system; entry manifest.systems.${system} or (throw Aspire CLI does not publish a Nix package for system ${system}.); isLinux stdenv.hostPlatform.isLinux; linuxLibraries [ icu openssl zlib stdenv.cc.cc.lib ]; linuxLibraryPath lib.makeLibraryPath linuxLibraries;从清单中取出当前系统的entry含rid、archiveName、url、hash仅在 Linux 上引入autoPatchelfHook与动态库依赖darwin 平台依赖系统自带库不需要这些输入。4.3 固定输出的源码抓取src fetchurl { inherit (entry) url hash; };这是固定输出fixed-output的关键url指向版本化的releases/download/vversion/aspire-cli-rid-version.tar.gzhash为对应的 Nix SRI 哈希sha512-...形式。Nix 会校验下载内容与哈希完全一致一旦上游变更即失效从而保证可复现性。同时注意url 字段永远是公开的版本化 release 下载地址见 README 与脚本注释而不是可变的aka.ms渠道重定向——这保证了固定输出 fetch 的确定性。4.4 构建阶段纯搬运 包装sourceRoot .; nativeBuildInputs [ makeWrapper ] lib.optionals isLinux [ autoPatchelfHook ]; buildInputs lib.optionals isLinux linuxLibraries; dontConfigure true; dontBuild true; dontStrip true; installPhase runHook preInstall mkdir -p $out/lib/aspire-cli $out/bin cp -R . $out/lib/aspire-cli/ chmod 755 $out/lib/aspire-cli/aspire printf %s\n {source:nix} $out/lib/aspire-cli/.aspire-install.json makeWrapper $out/lib/aspire-cli/aspire $out/bin/aspire ${lib.optionalString isLinux --prefix LD_LIBRARY_PATH : ${linuxLibraryPath}} runHook postInstall ;这一步揭示了包内的最终布局完整归档原样保留Release 归档已经包含完整的 CLI 包自包含的 .NET 原生二进制因此dontConfigure/dontBuild/dontStrip全部置真只做解包搬运二进制与 sidecar 同目录存放真实二进制放在$out/lib/aspire-cli/aspire旁边写入.aspire-install.json内容为{source:nix}对外包装$out/bin/aspire是由makeWrapper生成的用户入口在 Linux 上通过--prefix LD_LIBRARY_PATH注入icu、openssl、zlib、glibc的运行库路径autoPatchelfHook负责把 ELF 的依赖补到可解析状态。4.5 sidecarNix 在 Aspire 安装路由体系中的身份.aspire-install.json正是 Aspire CLI 的安装路由 sidecarinstall-route sidecar。在源码侧InstallSource.cs 定义了完整的安装来源枚举其中Nix对应的线格式wire string正是nix/// summaryNix package or flake install./summary Nix, // ... internal const string NixWire nix;CLI 在运行时通过读取二进制旁的.aspire-install.json的source字段判断自己是从哪种途径安装的script / pr / winget / brew / dotnet-tool / localhive / nix。这一身份在 docs/specs/install-routes.md 中有详细契约说明并直接影响 CLI 的自更新行为与数据目录选择Nix 安装被归类为只读包管理器路由包输出位于只读的 Nix store 中CLI 不应尝试写回二进制所在目录因此 Nix 路由回落到默认 Aspire home设置了ASPIRE_HOME时用该环境变量否则为$HOME/.aspire作为数据目录见 install-routes.md 中对nix的说明BundleService.ComputeDefaultExtractDir是布局选择的唯一事实来源布局是 sidecarsource值的纯函数未知source与已知只读路由如nix都回落到默认 Aspire home避免向二进制旁写入。4.6 包元数据passthru { inherit manifest; inherit (entry) archiveName rid; }; meta { description Command line tool for Aspire developers; homepage https://aspire.dev; changelog https://github.com/microsoft/aspire/releases/tag/${manifest.releaseTag}; license lib.licenses.mit; sourceProvenance with lib.sourceTypes; [ binaryNativeCode ]; platforms builtins.attrNames manifest.systems; mainProgram aspire; };passthru暴露manifest、archiveName、rid供外部消费meta中值得注意的两点sourceProvenance明确声明这是binaryNativeCode二进制原生代码包而非源码构建产物mainProgram aspire让nix run等工具能自动找到可执行入口。五、版本清单versions.json固定哈希的数据源versions.json 是 flake 的真相文件当前示例仓库现状为版本13.4.6、release tagv13.4.6包含四个系统的条目。每个条目形如x86_64-linux: { rid: linux-x64, archiveName: aspire-cli-linux-x64-13.4.6.tar.gz, url: https://github.com/microsoft/aspire/releases/download/v13.4.6/aspire-cli-linux-x64-13.4.6.tar.gz, hash: sha512-kYL/Wsf5TjmZRkAScf0dyxAfwp4MiZm2COlH9wI1TTCwnbTes6dunDqx3OBMc2eEe4or50PFjnqjpD5CIw8IRQ }version/releaseTag稳定版号与其对应的v前缀 tagrid归档的运行时标识符archiveName归档文件名遵循aspire-cli-rid-version.tar.gz约定url不可变的版本化下载地址GitHub immutable releasehashNix SRI 格式sha512-base64的固定输出哈希。由于flake.nix通过builtins.fromJSON (builtins.readFile ./eng/nix/versions.json)读取清单修改这个文件即修改 flake 的分发内容——这也是下文版本更新机制的核心对象。六、版本更新机制自动流水线与手动脚本双通道6.1 自动通道随稳定版发布联动README 描述的更新链路为细节可交叉印证 docs/release-process.md 与 docs/ci/native-cli-packaging.md稳定版发布时release-publish-nugetAzure DevOps 流水线派发.github/workflows/update-nix-cli-flake.yml流水线从签名源码构建的BlobArtifacts中读取aspire-cli-*.tar.gz.sha512校验和也就是它校验并上传到 release 的同一批构件作为输入传给 workflowworkflow 据此构建清单——清单基于构建产物而非 GitHub Release这样在 release 仍是未发布的draft时就能生成清单GitHub 不可变 release 的约束draft 资产不会通过公开的releases/download/...URL 提供workflow 将 Nix 清单变更提交到release-github-tasks.yml创建的update-baseline-version分支并创建/更新基线 PR使发布后的稳定版更新聚合在一起。合并基线 PR 就是仓库内 Nix 的 ship 步骤它把main上的 flake 元数据更新为指向 GitHub release 资产与哈希url字段始终是公开的版本化下载 URL发布管理员把 draft 转为正式发布后即生效。本仓库没有单独的 Nix registry 发布步骤。6.2 手动通道针对已发布版本对已经发布的稳定版可直接运行eng/nix/update-versions.sh --version stable-release-version脚本默认行为是下载每个官方.sha512校验和资产公开下载 URLcurl换算成 Nix SRI 哈希后重写versions.json。6.3 离线模式release 流水线的调用契约当发布流水线运行时它改用--sha512 ridhex参数直接传入四个平台的十六进制摘要完全不读 releaseeng/nix/update-versions.sh --version 13.4.6 \ --sha512 osx-arm64hex \ --sha512 osx-x64hex \ --sha512 linux-arm64hex \ --sha512 linux-x64hex脚本头注释明确说明了这一离线契约。脚本实现中有几个值得注意的工程细节离线模式强约束只要传入任意一个--sha512就进入离线模式且四个平台必须全部提供sha512_override_for逐 RID 查找缺失即报错不允许混用部分传入 部分 curl保证结果可复现版本校验只接受稳定版x.y.z去掉前导v/V后匹配^[0-9]\.[0-9]\.[0-9]$prerelease/daily 渠道有意不写入——因为 Nix 固定输出 fetch 必须保证消费者钉住仓库后仍可复现校验和解析.sha512资产可能是纯 hex 或hex 文件名两列格式脚本只取第一 tokenread -r checksum _hex → SRI 转换hex_sha512_to_sri先规范化大小写与空白兼容 Windows/Unix 换行校验必须是 128 位 hex再用xxd -r -p | base64输出sha512-base64格式原子写入先写versions.json.tmp兄弟文件四个平台全部解析、哈希成功后才mv覆盖正式清单curl/哈希失败不会留下半成品bash 3.2 兼容sha512_override_for特意不用关联数组sha512_override_for注释说明保证在 macOS 自带的旧 bash 上本地测试也能运行。无论自动还是手动清单始终使用版本化 GitHub release URL而非可变的aka.ms渠道重定向确保 Nix 固定输出 fetch 的可复现性。七、与上游 nixpkgs 的关系README 明确说明本 flake 是仓库内的第一方包而上游NixOS/nixpkgs中的 derivation 可以复用相同的 release 资产 URL 形态、RID 映射与nix安装路由 sidecar 行为从而在 nixpkgs 中提供pkgs.aspire-cli体验。也就是说本仓库的打包定义了标准形态归档命名、哈希、sidecar、布局上游 nixpkgs 包与该形态保持一致即可让用户通过普通 nixpkgs 渠道安装二者面向同一份官方 release 资产来源一致、行为一致。八、实践小结与适用前提场景推荐方式命令/配置临时体验nix runnix run github:microsoft/aspire#aspire-cli本机常驻nix profile addnix profile add github:microsoft/aspire#aspire-cli项目 devShell 集成跟随式 flake input见 2.3 节示例统一 overlay 管理aspire.overlays.default见 2.4 节示例手动升级已发布版本update-versions.sheng/nix/update-versions.sh --version 稳定版发布流水线离线升级--sha512离线模式见 6.3 节适用前提与限制仅支持四个平台见第三节映射表其余系统在求值期直接抛错只跟踪稳定版x.y.zpreview/daily 渠道不会进入versions.json安装后属于只读包管理器路由CLI 数据落到默认 Aspire homeASPIRE_HOME或$HOME/.aspire不会修改 store 内的二进制该打包消费官方 release 二进制归档不在 Nix 侧从源码构建 Aspire 仓库。延伸阅读安装路由 sidecar 的完整契约见 docs/specs/install-routes.mdNix 打包在发布流程中的位置见 docs/release-process.md原生 CLI 打包与签名相关细节见 docs/ci/native-cli-packaging.mdsidecar 的读写与原子更新实现见 src/Aspire.Cli/Acquisition/InstallSidecarWriter.cs 与 src/Aspire.Cli/Acquisition/InstallSidecarReader.cs。【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考