git 依赖 ​

核心概念 ​

Git 依赖允许 Cargo 直接从 Git 仓库获取 crate 的源码,而不是从 crates.io 注册中心下载。这在以下场景中非常有用:crate 尚未发布到 crates.io、需要使用上游仓库中尚未发布的最新修复、或者依赖私有仓库中的代码。

Git 依赖通过 git 键指定仓库 URL,可以搭配 branch、tag 或 rev 来精确控制获取哪个版本的代码。Cargo 首次获取后会将精确的提交 hash 锁定在 Cargo.lock 中,后续构建不会自动拉取新提交,需要 cargo update 来更新。

toml
[dependencies]
# 默认分支的最新提交
my-lib = { git = "https://github.com/user/my-lib" }

# 指定分支
my-lib = { git = "https://github.com/user/my-lib", branch = "develop" }

# 指定标签
my-lib = { git = "https://github.com/user/my-lib", tag = "v2.0.0" }

# 指定精确提交
my-lib = { git = "https://github.com/user/my-lib", rev = "a1b2c3d4" }

指定版本方式 ​

toml
[dependencies]
# === branch:跟踪分支 ===
# 获取指定分支的最新提交
# cargo update 时会拉取该分支的最新代码
my-lib = { git = "https://github.com/user/my-lib", branch = "main" }

# === tag:指定标签 ===
# 标签通常对应一个发布版本
# 比 branch 更稳定,适合生产使用
my-lib = { git = "https://github.com/user/my-lib", tag = "v1.5.0" }

# === rev:指定提交 hash ===
# 最精确的方式,完全不受后续提交影响
# cargo update 也不会改变版本
my-lib = { git = "https://github.com/user/my-lib", rev = "8a3b2c1e" }

# === 不指定:使用默认分支 ===
# 等同于 branch = "HEAD"
my-lib = { git = "https://github.com/user/my-lib" }
方式稳定性cargo update 行为适用场景
branch中拉取该分支最新提交跟踪开发进度
tag高不变(标签不变的前提下)使用特定发布版本
rev最高不变精确锁定某次提交
不指定低拉取默认分支最新提交快速试用

Git 仓库中的多 crate ​

toml
# 如果一个 Git 仓库包含多个 crate(monorepo),
# 默认 Cargo 会查找仓库根目录的 Cargo.toml。
# 需要用 path 指定子目录中的 crate。

# monorepo 中的子 crate
my-core = { git = "https://github.com/user/monorepo", path = "crates/core" }
my-utils = { git = "https://github.com/user/monorepo", path = "crates/utils" }

# 同一个仓库的多个 crate 只会被 clone 一次

私有仓库 ​

toml
# === SSH 协议(推荐用于私有仓库) ===
my-lib = { git = "ssh://git@github.com/org/private-repo.git" }

# SSH 简写格式也可以
my-lib = { git = "ssh://git@github.com/org/private-repo" }

# === HTTPS + 凭证 ===
# 需要配置 Git 凭证管理器或 .netrc 文件
my-lib = { git = "https://github.com/org/private-repo" }

# === .cargo/config.toml 中配置凭证 ===
# [net]
# git-fetch-with-cli = true    # 使用系统 git 命令(支持 SSH agent)

[patch] 段替换依赖 ​

toml
# [patch] 允许临时用 Git 版本替换 crates.io 上的版本
# 常用于调试上游 bug 或测试补丁

[dependencies]
serde = "1.0"    # 正常依赖 crates.io 版本

[patch.crates-io]
# 临时用 fork 版本替换
serde = { git = "https://github.com/my-fork/serde", branch = "fix-bug" }

# 也可以用本地路径替换
# serde = { path = "../serde-local" }

基本示例 ​

toml
# 一个使用 Git 依赖的项目配置

[package]
name = "my-app"
version = "0.1.0"
edition = "2024"

[dependencies]
# 稳定依赖:从 crates.io
serde = { version = "1", features = ["derive"] }
tokio = { version = "1", features = ["full"] }

# 内部库:从私有 Git 仓库
internal-sdk = { git = "ssh://git@github.com/company/sdk.git", tag = "v0.5.0" }

# 试验性依赖:从 Git 跟踪开发分支
new-framework = { git = "https://github.com/user/new-framework", branch = "main" }
rust
fn main() {
    // Git 依赖在代码中的使用方式与 crates.io 依赖完全相同
    // use internal_sdk::Client;
    // use new_framework::App;

    println!("Git 依赖和普通依赖在代码中没有区别");
    println!("运行 cargo update 更新 Git 依赖的锁定版本");
}

常见问题 ​

问题一:Git 依赖的代码存储在哪里?

Cargo 将 Git 仓库克隆到 $CARGO_HOME/git/ 目录下(默认是 ~/.cargo/git/)。db/ 子目录存储裸仓库,checkouts/ 子目录存储工作副本。

问题二:Git 依赖可以发布到 crates.io 吗?

不能。发布到 crates.io 的 crate 不能有纯 Git 依赖。必须将依赖也发布到 crates.io 并使用 version 指定,或者使用 [patch] 段在本地开发时临时替换。

问题三:怎么强制更新 Git 依赖?

cargo update -p crate_name 更新特定依赖,cargo update 更新所有依赖。如果指定了 rev,cargo update 不会改变版本。

问题四:CI/CD 环境中怎么处理私有 Git 依赖?

在 CI 环境中配置 SSH 密钥或 Git 凭证。可以在 .cargo/config.toml 中设置 git-fetch-with-cli = true 使用系统 Git(支持 SSH agent)。也可以用环境变量 CARGO_NET_GIT_FETCH_WITH_CLI=true。

适用场景 ​

  • 未发布的 crate:依赖尚未发布到 crates.io 的库
  • 私有代码:公司内部的私有 crate
  • 上游修复:使用上游仓库中已修复但未发布的版本
  • 开发预览:跟踪开发分支试用新功能
  • Monorepo:从一个仓库中引用多个 crate

注意事项 ​

  • Git 依赖的精确提交会锁定在 Cargo.lock 中
  • cargo update 才会拉取新提交
  • Git 依赖不能发布到 crates.io
  • 私有仓库需要配置 SSH 密钥或 Git 凭证
  • 同一仓库的多个依赖只会 clone 一次
  • branch、tag、rev 三者只能指定其一

总结 ​

Git 依赖通过 git 键指定仓库 URL,从远程 Git 仓库获取 crate 源码。可以用 branch 跟踪分支、tag 指定标签、rev 锁定精确提交。Cargo 首次获取后将提交 hash 锁定在 Cargo.lock 中,cargo update 才会拉取新版本。Git 依赖不能发布到 crates.io,适用于未发布的 crate、私有仓库和上游修复等场景。私有仓库可以通过 SSH 协议或 Git 凭证管理器访问。[patch] 段可以临时用 Git 版本替换 crates.io 上的依赖。