Cargo 更換 cargo 源

更換 cargo 源 —— 附目前可用國內 cargo 鏡像源配置

本文檔是關于更換 crate 索引(注冊表)。您可以閱讀有關重寫依賴項的信息，它在本文檔的重寫依賴關系部分。

Cargo 支持用另一個來源更換一個來源的能力，可根據(jù)鏡像或 vendoring 依賴關系來表達傾向。要配置這些，目前通過.cargo/config配置機制完成，像這樣:

# `source` 表下，就是存儲有關要更換的來源名稱
[source]

# 在`source` 表格之下的，可為一定數(shù)量的有關來源名稱. 示例下面就# 定義了一個新源， 叫 `my-awesome-source`， 其內容來自本地 # `vendor`目錄 ，其相對于包含`.cargo/config`文件的目錄
[source.my-awesome-source]
directory = "vendor"

# Git sources 也指定一個 branch/tag/rev
git = "https://example.com/path/to/repo"
# branch = "master"
# tag = "v1.0.1"
# rev = "313f44e8"

# The crates.io 默認源 在"crates-io"名稱下， 且在這里我們使用 `replace-with` 字段指明 默認源更換成"my-awesome-source"源
[source.crates-io]
replace-with = "my-awesome-source"

使用此配置，Cargo 會嘗試在"vendor"目錄中，查找所有包，而不是 查詢在線注冊表 crates.io 。Cargo 有兩種來源更換的表達 :

• 供應(Vendoring) - 可以定義自定義源，它們表示本地文件系統(tǒng)上的包。這些源是它們正在更換的源的子集，并在需要時可以檢入包中。

• 鏡像(Mirroring) - 可以更換為等效版本的源，行為表現(xiàn)為 crates.io 本身的緩存。

Cargo 有一個關于來源更換的核心假設，源代碼從兩個完全相同的源而來。在上面的例子中，Cargo 假設所有的箱子都來自my-awesome-source，與crates-io副本完全相同。請注意，這也意味著my-awesome-source，不允許有crates-io源不存在的箱。

因此，來源更換不適用于依賴項補丁(fix bug)，或私有注冊表等情況。Cargo 是通過使用[replace]字段支持依賴項補丁，計劃為未來版本的 Cargo 提供私人注冊表的支持。

配置

更換源的配置通過完成.cargo/config，下面為全套可用字段是:

# 每個源都有自己的表格，名稱即是表名
[source.the-source-name]

# 命令 ，`the-source-name` 會被`another-source`取代
replace-with = "another-source"

# 有幾種可用的源定義(接下來有所描述)
registry = "https://example.com/path/to/index"
local-registry = "path/to/registry"
directory = "path/to/vendor"

crates-io代表 crates.io 在線注冊表(箱的默認來源)，可以更換為:

[source.crates-io]
replace-with = 'another-source'

注冊表源

"注冊表源"與 crates.io 本身相同。也就是說，它也有一個在 git 存儲庫中提供的索引，該存儲庫匹配crates.io index的格式。然后該存儲庫具有指示從哪里下載包的配置。

目前還沒有一個已經設置 crates.io 的鏡像的可用項目。請繼續(xù)關注!

以下配置由芽之家書館搜集驗證，并持續(xù)更新——

中國大陸用戶，因為網絡原因，推薦使用國內鏡像源。目前國內 cargo 鏡像源有：中國科學技術大學源、上海交通大學源、清華大學源，以及 rustcc 社區(qū)源。

自定義 cargo 源有兩種方法，推薦使用第一種——

• 創(chuàng)建 $HOME/.cargo/config 文件（各操作系統(tǒng)及版本均大致相同），然后在 config 文件內寫入下述配置內容。其中協(xié)議推薦使用 git，但對于 https 和 git 協(xié)議，一般各鏡像源都支持，并且是可以互換的。如果你所處的環(huán)境中不允許使用 git 協(xié)議，或者配置 git 協(xié)議后不能正常獲取和編譯 crate，可以換 https 協(xié)議再試試。

[source.crates-io]
registry = "https://github.com/rust-lang/crates.io-index"
# 指定鏡像
replace-with = '鏡像源名' # 如：tuna、sjtu、ustc，或者 rustcc

# 注：以下源配置一個即可，無需全部

# 中國科學技術大學
[source.ustc]
registry = "https://mirrors.ustc.edu.cn/crates.io-index"
# >>> 或者 <<<
registry = "git://mirrors.ustc.edu.cn/crates.io-index"

# 上海交通大學
[source.sjtu]
registry = "https://mirrors.sjtug.sjtu.edu.cn/git/crates.io-index/"

# 清華大學
[source.tuna]
registry = "https://mirrors.tuna.tsinghua.edu.cn/git/crates.io-index.git"

# rustcc社區(qū)
[source.rustcc]
registry = "https://code.aliyun.com/rustcc/crates.io-index.git"

• 或者在項目工程結構中，與 Cargo.toml 同級目錄的 .cargo 文件夾下創(chuàng)建 config 文件，config 文件配置方法和內容與第一種相同。

本地 注冊表源

"本地注冊表源"旨在成為另一個注冊表源的子集，但可在本地文件系統(tǒng)(也稱為 vendoring)上使用。本地注冊表是提前下載，通常與一個 Cargo.lock同步，并由一組*.crate文件和像普通注冊表一樣的索引組成。

管理和創(chuàng)建本地注冊表源的主要方法是通過cargo-local-registry子命令，可在 crates.io 上找到，并用cargo install cargo-local-registry安裝。

本地注冊表包含在一個目錄，其中包含許多從 crates.io 下載的*.crate文件，以及index目錄，它與 crates.io-index 項目目錄具有相同格式(僅填充有存在的 crates).

目錄 源

"目錄源"類似于本地注冊表源，其中包含本地文件系統(tǒng)上許多的可用包，適用于 vendoring 依賴項。與本地注冊表一樣，目錄源主要由外部子命令管理cargo-vendor，可用cargo install cargo-vendor安裝。

目錄源與本地注冊表不同，但它們包含*.crate文件的解壓縮版本，使其在某些情況下，更適合檢查所有內容到源代碼控制工具。目錄源只是一個包含許多其他目錄的目錄，其中包含 crates 的源代碼(解壓縮版本的*.crate文件)。目前，對每個目錄的名稱沒有限制。

目錄源中的每個包也有一個關聯(lián)的元數(shù)據(jù)文件，指示包中每個文件的校驗和，以防止意外修改。