path 与 git 依赖
核心概念
除了从 crates.io 获取依赖外,Cargo 还支持从本地路径和 Git 仓库获取依赖。路径依赖(path dependency)指向本地文件系统上的另一个 Cargo 包,常用于多包项目(workspace)或本地开发时的临时替换。Git 依赖从远程 Git 仓库获取代码,可以指定分支、标签或具体提交。
[dependencies]
# 路径依赖:指向本地的另一个 crate
my-utils = { path = "../my-utils" }
my-core = { path = "crates/core" }
# Git 依赖:从 Git 仓库获取
my-lib = { git = "https://github.com/user/my-lib" }
# Git 依赖 + 指定分支
my-lib = { git = "https://github.com/user/my-lib", branch = "develop" }
# Git 依赖 + 指定标签
my-lib = { git = "https://github.com/user/my-lib", tag = "v1.0.0" }
# Git 依赖 + 指定提交
my-lib = { git = "https://github.com/user/my-lib", rev = "a1b2c3d" }路径依赖
# 路径依赖的典型用法
# === 单一路径 ===
[dependencies]
my-utils = { path = "../my-utils" }
# === 路径 + 版本(用于发布)===
# 发布到 crates.io 时,path 会被忽略,使用 version 从注册中心获取
my-utils = { path = "../my-utils", version = "0.1" }
# === workspace 中的路径依赖 ===
# 在 workspace 成员之间相互依赖时使用
[dependencies]
my-core = { path = "../core" }
my-macros = { path = "../macros" }# 典型的 workspace 目录结构
my-project/
├── Cargo.toml # workspace 根配置
├── app/
│ ├── Cargo.toml # 依赖 core 和 macros
│ └── src/main.rs
├── core/
│ ├── Cargo.toml
│ └── src/lib.rs
└── macros/
├── Cargo.toml
└── src/lib.rs// app/src/main.rs
// 使用路径依赖的 crate
// use my_core::SomeType;
// use my_macros::SomeMacro;
fn main() {
println!("路径依赖允许在本地多包项目中互相引用");
}Git 依赖
# === 默认:使用默认分支的最新提交 ===
[dependencies]
my-lib = { git = "https://github.com/user/my-lib" }
# === 指定分支 ===
my-lib = { git = "https://github.com/user/my-lib", branch = "main" }
my-lib-dev = { git = "https://github.com/user/my-lib", branch = "develop" }
# === 指定标签 ===
my-lib = { git = "https://github.com/user/my-lib", tag = "v2.0.0" }
# === 指定提交 hash ===
my-lib = { git = "https://github.com/user/my-lib", rev = "8a3b2c1" }
# === Git 仓库中的子目录 ===
# 当 Git 仓库包含多个 crate 时
my-sub = { git = "https://github.com/user/monorepo", path = "crates/sub" }
# === SSH 协议 ===
my-lib = { git = "ssh://git@github.com/user/my-lib.git" }
# === Git 依赖 + features ===
my-lib = { git = "https://github.com/user/my-lib", features = ["serde"] }发布时的注意事项
# 发布到 crates.io 时:
# - 路径依赖必须同时指定 version
# - Git 依赖不能发布(必须改为 version 依赖)
# 正确:可以发布
[dependencies]
my-utils = { path = "../my-utils", version = "0.1.0" }
# 错误:无法发布到 crates.io
# my-lib = { git = "https://github.com/user/my-lib" }
# my-local = { path = "../my-local" } # 没有 version
# 解决方案:开发时用 path/git,发布时切换为 version
# 或者使用 [patch] 段临时覆盖基本示例
# 一个使用混合依赖的实际项目
[package]
name = "my-app"
version = "0.1.0"
edition = "2024"
[dependencies]
# 从 crates.io 获取(生产依赖)
serde = { version = "1", features = ["derive"] }
tokio = { version = "1", features = ["full"] }
# 从本地路径获取(workspace 内部依赖)
my-core = { path = "../core", version = "0.1" }
my-macros = { path = "../macros", version = "0.1" }
# 从 Git 获取(未发布的依赖或使用最新修复)
experimental = { git = "https://github.com/user/experimental", branch = "main" }
[patch.crates-io]
# 临时使用本地修改版本替代 crates.io 上的版本
# 调试或修复 bug 时使用
# serde = { path = "../serde-fork" }fn main() {
println!("路径依赖:本地开发和 workspace");
println!("Git 依赖:未发布的 crate 或使用最新修复");
println!("发布时:路径依赖需要 version,Git 依赖需要替换");
}常见问题
问题一:路径依赖的路径是相对于什么?
相对于当前 Cargo.toml 所在的目录。{ path = "../my-lib" } 表示上一级目录中的 my-lib 文件夹。
问题二:Git 依赖多久更新一次?
Git 依赖的精确版本会被锁定在 Cargo.lock 中。只有运行 cargo update 时才会拉取最新提交。指定 rev 的依赖不会自动更新。
问题三:能同时指定 path 和 git 吗?
不能。path、git 和 version(从注册中心获取)三种来源互斥(path + version 除外,这是为了支持发布)。
问题四:Git 依赖支持私有仓库吗?
支持。使用 SSH 协议(git = "ssh://git@github.com/...")或配置 Git 凭证即可。需要确保构建环境有访问权限。
适用场景
- Workspace 成员互相依赖:路径依赖
- 本地临时调试 fork 版本:路径依赖 +
[patch] - 使用未发布到 crates.io 的 crate:Git 依赖
- 使用上游修复但未发布的补丁:Git 依赖 + rev/tag
注意事项
- 发布到 crates.io 时,路径依赖必须同时有
version - Git 依赖不能直接发布到 crates.io
- Git 依赖的版本锁定在 Cargo.lock 中
cargo update -p crate_name可以单独更新某个 Git 依赖- 路径依赖的修改会被 Cargo 自动检测并重新编译
- Git 仓库中可以用
path参数指定子目录中的 crate
总结
路径依赖(path)指向本地文件系统上的 crate,常用于 workspace 内部和本地开发调试。Git 依赖(git)从远程仓库获取代码,可以指定分支(branch)、标签(tag)或提交(rev)。发布到 crates.io 时,路径依赖必须同时指定 version,Git 依赖则不能发布。Git 依赖的精确版本锁定在 Cargo.lock 中,cargo update 才会拉取最新提交。两种方式都支持 features、default-features 等选项。