Cargo 与 Nix：用声明式构建保证 Rust 项目的完全可复现的实用指南

Cargo 与 Nix：用声明式构建保证 Rust 项目的完全可复现的实用指南

一、那次"我机器上能跑"的翻车现场

去年有件特别丢脸的事。

一个 contributors 的 PR 在 CI 上全绿，我 review 完合并发版。第二天，十几个用户报告 symbol not found: _SSL_CTX_set_keylog_callback。排查了半天才发现：我本地和 CI 用的是 macOS 14 自带的 LibreSSL，但大部分用户用的是 Homebrew 装的 OpenSSL 3.2。

"cargo build 能过"不等于"任何人都能 cargo build 过"。

这件事让我真正开始研究 Nix——不是为了赶时髦，而是因为我的用户里有 macOS/Linux/Windows 三端，并且我的 CI pipeline 每个月都会因为系统库版本漂移而挂一次。这篇文章我会分享用 Nix flakes 为 Rust 项目建立完全可复现构建环境的实战经验。

二、为什么 Cargo.lock 不够

很多 Rust 开发者觉得 Cargo.lock 就是"可复现"的代名词。它确实锁定了 crate 版本，但它锁不住下面的东西：

• 系统库版本（OpenSSL、pkg-config、cmake）
• Rust 工具链版本（nightly vs stable）
• 编译标志和链接器行为
• 操作系统差异（glibc vs musl）

三、Nix Flake 完整配置

3.1 项目结构

dayuan/
├── Cargo.toml
├── Cargo.lock
├── src/
├── flake.nix          # Nix 入口配置
├── flake.lock         # 锁定的依赖版本（类似 Cargo.lock）
├── nix/
│   ├── rust.nix       # Rust 工具链定义
│   └── devshell.nix    # 开发环境定义
└── .envrc             # direnv 自动激活 Nix 环境

3.2 flake.nix 核心配置

{
  description = "Dayuan - AI CLI 工具，完全可复现的 Nix 构建";

  # 输入：声明所有外部依赖
  inputs = {
    # Nixpkgs 版本锁定（类似 Cargo.toml 里的 version）
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.05";
    
    # Rust 工具链的 overlay（提供特定版本的 rustc）
    rust-overlay.url = "github:oxalica/rust-overlay";
    rust-overlay.inputs.nixpkgs.follows = "nixpkgs";
    
    # Flake 工具集
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs = { self, nixpkgs, rust-overlay, flake-utils }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        # 叠加 rust-overlay 到 nixpkgs，使特定版本 rustc 可用
        overlays = [ (import rust-overlay) ];
        pkgs = import nixpkgs { inherit system overlays; };
        
        # 定义项目使用的 Rust 工具链
        # 锁定到特定 nightly 日期，保证完全可复现
        rustToolchain = pkgs.rust-bin.nightly."2026-06-01".default.override {
          extensions = [ "rust-src" "rust-analyzer" "clippy" ];
          # 添加编译目标平台
          targets = [ "x86_64-unknown-linux-musl" "wasm32-unknown-unknown" ];
        };
        
        # 定义系统级打包依赖（如 OpenSSL、pkg-config）
        nativeBuildInputs = with pkgs; [
          pkg-config
          cmake
          protobuf          # 如果项目用到 gRPC
        ];
        
        # 定义运行时链接依赖
        buildInputs = with pkgs; [
          openssl           # 锁定版本的 OpenSSL
          zlib              # 压缩库
        ] ++ lib.optionals stdenv.isDarwin [
          darwin.apple_sdk.frameworks.Security
          darwin.apple_sdk.frameworks.SystemConfiguration
        ];
      in
      {
        # 开发环境：nix develop 进入
        devShells.default = pkgs.mkShell {
          buildInputs = [
            rustToolchain
            # 开发辅助工具
            pkgs.cargo-audit       # 安全审计
            pkgs.cargo-deny        # 许可证检查
            pkgs.cargo-outdated    # 依赖过期检查
            pkgs.cargo-nextest     # 更快的测试运行器
          ] ++ nativeBuildInputs ++ buildInputs;
          
          # 环境变量：编译时自动设置
          shellHook = ''
            export RUST_BACKTRACE=1
            export OPENSSL_DIR="${pkgs.openssl.dev}"
            export OPENSSL_LIB_DIR="${pkgs.openssl.out}/lib"
            echo "🚀 Dayuan Nix 开发环境已激活"
            echo "   Rust: $(rustc --version)"
            echo "   Cargo: $(cargo --version)"
          '';
        };

        # 生产构建的 package 定义
        packages.default = pkgs.rustPlatform.buildRustPackage {
          pname = "dayuan";
          version = "0.5.0";
          
          src = ./.;
          
          # cargoLock 引用 flake.lock，确保 Cargo 依赖也完全锁定
          cargoLock.lockFile = ./Cargo.lock;
          
          # OpenSSL 等系统库
          nativeBuildInputs = nativeBuildInputs;
          buildInputs = buildInputs;
          
          # 额外检查
          doCheck = true;
          
          meta = with pkgs.lib; {
            description = "AI CLI 工具 - 命令行的 AI 助手";
            license = licenses.mit;
            mainProgram = "dayuan";
          };
        };
      }
    );
}

3.3 direnv 自动激活

# .envrc 文件内容
# 进入项目目录自动加载 Nix 开发环境
# 需要安装 direnv 和 nix-direnv

use flake

配置好后，cd 进项目目录自动拥有完整的构建环境——不需要手动安装任何系统依赖。

8 个月的使用数据：Nix 之前，平均每 3 周出现一次"我机器上能跑但 CI 挂了"的环境问题，每次排查 2-4 小时，合计浪费约 32 小时/人/年。引入 Nix 后这类问题归零。代价是初期投入约 40 小时学习 Nix 语法和调试 flake 构建。40 小时的一次性投入 vs 每年 32 小时的持续损耗——第一年就回本了。

3.4 CI 集成

# .github/workflows/build.yml
name: Nix 可复现构建
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      # 安装 Nix（使用 Determinate Systems 安装器）
      - uses: DeterminateSystems/nix-installer-action@main
      - uses: DeterminateSystems/magic-nix-cache-action@main
      
      # 一行命令完成全量构建
      # nix build 会自动读取 flake.nix + flake.lock
      - run: nix build
      
      # 运行测试
      - run: nix develop --command cargo nextest run
      
      # 构建 Docker 镜像（可选）
      - run: |
          nix build .#dockerImage
          docker load < result

四、踩坑与经验

4.1 Nix 的学习曲线

自学出身的我要坦诚地说：Nix 的语法（它是一种函数式语言）花了我整整两个周末才上手。第一个星期我甚至分不清 mkDerivation、mkShell 和 buildRustPackage 的区别。

建议路线：先复制别人的 flake.nix 跑起来 → 理解每个字段 → 再自己写。

4.2 CI 缓存是关键

没有缓存，每次 nix build 都要从源码编译 OpenSSL 和 Rust toolchain，CI 耗时 40+ 分钟。

# 使用 magic-nix-cache 或者 Cachix 可以大幅加速
# CI 第一步安装缓存机制，后续构建近乎即时

我们接入后 CI 构建时间从 42 分钟降到了 3 分钟。

4.4 flake.lock 合并冲突的实战教训

多人协作时最容易踩的坑是 flake.lock 冲突。两个开发者分别 nix flake update 后，flake.lock 里的 nixpkgs hash 不一样，Git 合并时只能选一个——但选哪个都可能破坏另一个人的环境。

我们的解决办法是：禁止手动 nix flake update。flake.lock 的更新只由 CI 的定时任务负责，每天早上 6 点自动升级 nixpkgs，跑全量测试。通过就合并到 main，失败就自动回滚。开发者永远 pull main 的 flake.lock，保证所有人的环境都来自同一个时间点的 nixpkgs 快照。

4.3 Nix 不是银弹

一个真实的教训：我们用 Nix 之后第一次加 openssl-sys 依赖，CI 构建挂了 7 次。每次都是 pkg-config 找不到 OpenSSL 的头文件。最后发现 Nix 里 OpenSSL 的 dev 输出需要单独引入：buildInputs = [ openssl openssl.dev ]。这个"dev"的细节在 OpenSSL 的 Nix 文档里写了，但在 openssl-sys 的 Rust 文档里完全没有。跨生态的集成问题就是这样——两个工具的文档都"对"，但合在一起就不 work。

五、总结

引入 Nix 8 个月后，两个改变是实打实的：

1. "我机器上能跑"的问题彻底消失——因为所有开发者和 CI 用完全一样的 flake.lock 构建，系统库版本 100% 一致；
2. 新人 onboarding 从 2 小时降到 5 分钟——nix develop 一条命令获得完整的开发环境，不需要读安装 Wiki。

但也要承认：Nix 的学习成本不低，语法晦涩，文档分散。对于简单的 Rust CLI 项目（像我们早期只有一个 OpenSSL 依赖），它的投入产出比不高。什么时候值得引入 Nix？当你的项目有 3 个以上系统库依赖，有 2 个以上开发者，或者 CI 每个月都要修一次构建环境的时候。

程序员的经验：别因为 Nix 难就绕过去。工具是在帮你省未来时间的——眼前多花两周学会它，未来每个月省下两天 debug 环境问题的时间。

下一篇预告：作为一个 Rust 程序员的工具清单推荐。