path 与 git 依赖 ​

核心概念 ​

除了从 crates.io 获取依赖外,Cargo 还支持从本地路径和 Git 仓库获取依赖。路径依赖(path dependency)指向本地文件系统上的另一个 Cargo 包,常用于多包项目(workspace)或本地开发时的临时替换。Git 依赖从远程 Git 仓库获取代码,可以指定分支、标签或具体提交。

toml
[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" }

路径依赖 ​

toml
# 路径依赖的典型用法

# === 单一路径 ===
[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
rust
// app/src/main.rs
// 使用路径依赖的 crate
// use my_core::SomeType;
// use my_macros::SomeMacro;

fn main() {
    println!("路径依赖允许在本地多包项目中互相引用");
}

Git 依赖 ​

toml
# === 默认:使用默认分支的最新提交 ===
[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"] }

发布时的注意事项 ​

toml
# 发布到 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] 段临时覆盖

基本示例 ​

toml
# 一个使用混合依赖的实际项目

[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" }
rust
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 等选项。