git 依赖
核心概念
Git 依赖允许 Cargo 直接从 Git 仓库获取 crate 的源码,而不是从 crates.io 注册中心下载。这在以下场景中非常有用:crate 尚未发布到 crates.io、需要使用上游仓库中尚未发布的最新修复、或者依赖私有仓库中的代码。
Git 依赖通过 git 键指定仓库 URL,可以搭配 branch、tag 或 rev 来精确控制获取哪个版本的代码。Cargo 首次获取后会将精确的提交 hash 锁定在 Cargo.lock 中,后续构建不会自动拉取新提交,需要 cargo update 来更新。
[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" }指定版本方式
[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
# 如果一个 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 一次私有仓库
# === 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] 段替换依赖
# [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" }基本示例
# 一个使用 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" }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 上的依赖。