發(fā)布到 crates.io

一旦你有一個你想與世界分享的 crate，就該把它發(fā)布到crates.io! 發(fā)布是指，上載特定版本的，以讓crates.io進行托管.

發(fā)布箱(crate)子時，要小心，因為發(fā)布是常駐。永遠不能覆蓋同版本，并且無法刪除代碼。但是，可以發(fā)布的版本數(shù)量沒有限制。

在你開始發(fā)布前

首先，你需要一個crates.io帳戶，用來獲取 API 令牌。為此，訪問主頁，并通過 GitHub 帳戶登錄(現(xiàn)在需要)。在此之后，訪問你的帳號設定頁面，并運行cargo login命令聯(lián)通賬號。

$ cargo login abcdefghijklmnopqrstuvwxyz012345

此命令將告訴 Cargo 關于您的 API 令牌，并將其存儲在您的本地~/.cargo/credentials(以前是~/.cargo/config)。請注意，此令牌是一個秘密，不應與其他任何人分享。如果因任何原因泄漏，您應立即重新生成。

在你創(chuàng)建新 crate 前

請記住crates.io上箱子的名字，會采取先到先得的方式分配。一旦獲得箱子名稱，它就不能用于另一個箱子.

打包一個 crate

下一步是，將您的包裝箱打包成可供crates.io上傳的格式。為此，我們將使用cargo package子命令。這將把我們的整個包裝箱全部打包成一個*.crate文件，其在target/package目錄中。

$ cargo package

作為一個額外的功能，*.crate將獨立于當前源樹進行驗證。在*.crate創(chuàng)建之后，會解壓到target/package目錄，然后從頭開始構建，以確保構建成功的所有必要文件。可以使用--no-verify參數(shù)禁用此行為。

現(xiàn)在是時候看看*.crate文件了，為了確保您不會意外地打包 2GB 視頻資源，或用于代碼生成，集成測試或基準測試的大型數(shù)據(jù)文件。目前存在 10MB 的*.crate文件上傳大小限制。所以，如果tests和benches目錄及其依賴項大小，最多只達 幾 MB，您仍可以將它們保存在包; 不然的話，最好排除它們。

在打包時，Cargo 會自動忽略版本控制系統(tǒng)的忽略文件，但是如果要指定要額外的忽略文件集，則可以使用清單中的exclude字段:

[package]
# ...
exclude = [
    "public/assets/*",
    "videos/*",
]

這個數(shù)組中每個元素接受的語法是rust-lang/glob。如果您寧愿使用白名單，而不是黑名單,Cargo 也支持include字段，如果設置,則會覆蓋exclude字段:

[package]
# ...
include = [
    "**/*.rs",
    "Cargo.toml",
]

上傳該 crate

現(xiàn)在我們已經(jīng)有了*.crate文件準備好了，可以上傳到crates.io，接著使用cargo publish命令就好。就是這樣，你現(xiàn)在已經(jīng)發(fā)布了你的第一個箱子!

$ cargo publish

如果你想跳過cargo package那一步，cargo publish如果找不到副本，子命令將自動打包本地包.

一定要看看您可以指定的元數(shù)據(jù)確保您的箱子更容易被發(fā)現(xiàn)!

為已存在的 crate，發(fā)布一個新版本

要發(fā)布新版本，請在Cargo.toml更改version為您指定的值。記住semver 規(guī)則。然后可選擇運行cargo package，如果你想檢查一下*.crate發(fā)布前的新版本文件，然后運行cargo publish上傳新版本.

管理一個 基于 crates.io 的 crate

箱的管理主要通過命令行完成cargo工具，而不是crates.io網(wǎng)絡界面。為此，有一些子命令來管理包.

cargo yank

在您發(fā)布時，實際上可能會因某種原因，而最終破壞的箱子版本(語法錯誤，忘記包含文件等)的情況。對于諸如此類的情況，Cargo 支持一個箱子版本的"yank"。

$ cargo yank --vers 1.0.1
$ cargo yank --vers 1.0.1 --undo

一個 yank 不是刪除任何代碼。例如，此功能不用于刪除意外上傳的機密。如果發(fā)生這種情況，您必須立即重置這些秘密.

一個 yank 版本的語義是，不為該版本創(chuàng)建新的依賴項，但所有現(xiàn)有的依賴項繼續(xù)有效。crates.io其中一個主要目標是作為永久存檔的箱子庫，不會隨著時間的推移而改變，而允許刪除版本將違背這一目標。所以基本上，一個 yank 意味著所有包的Cargo.lock不會被破壞，在任何的未來，Cargo.lock生成的文件不會列出 yank 的版本。(成為了一個孤島版本)

cargo owner

箱子通常由不止一個人開發(fā)，或者主要維護者可能會隨著時間而改變!箱子的所有者是唯一允許發(fā)布新版本箱子的人，但是所有者可以指定其他所有者。

$ cargo owner --add my-buddy
$ cargo owner --remove my-buddy
$ cargo owner --add github:rust-lang:owners
$ cargo owner --remove github:rust-lang:owners

給這些命令的所有者 ID 必須是 GitHub 用戶名或 GitHub 團隊.

如果用--add了一個用戶名，那該用戶成為"命名"所有者，擁有該箱子的完全權利。除了能夠發(fā)布或 yank 箱子的版本，他們還能夠添加或刪除所有者，包含任命他們的所有者。毋庸置疑，你不應該讓那些你不完全信任的人，作命名所有者。要成為命名所有者，用戶必須之前就已登錄crates.io。

如果用--add了一個團隊，那該團隊成為"團隊"所有者，對箱的權利受到限制。雖然他們有權發(fā)布或 yank 箱子的版本，但他們不能夠添加或刪除所有者。除了更方便管理所有者群體之外，團隊還可以更安全地防止惡意所有者。

團隊的目前的語法是github:org:team(見上面的例子)。要將團隊添加為所有者，必須是該團隊的成員。刪除所有者的團隊就沒有此類限制.

GitHub 權限

團隊成員資格，不是 GitHub 提供的簡單公共訪問權限，并且在使用它時可能會遇到以下消息:

您似乎無權從 GitHub 查詢必要的屬性，來完成此請求。您可能需要在crates.io重新進行身份驗證，并申請閱讀 GitHub 組織成員資格的權限。去https://crates.io/login看看

這基本上是一個全查詢防御，當"你試圖查詢團隊信息，而其中的五級成員訪問控制，拒絕了它"。這并不夸張。GitHub 對團隊訪問控制的支持是企業(yè)級.

最可能的原因是您最后一次登錄是在添加此功能之前。我們最初沒有要求 GitHub 對用戶進行身份驗證時的權限，因為我們實際上并沒有將用戶的令牌用于登錄以外的任何其他內容。但是，為了代表您能夠查詢團隊成員資格，我們現(xiàn)在需要read:org范圍權限。

您完全可以拒絕我們這個范圍，且在團隊介紹之前所做的一切，都將繼續(xù)有效。但是，您永遠無法將團隊添加為所有者，或者將團隊作為團隊所有者發(fā)布。如果您嘗試這樣做，您將收到上述錯誤。如果你試圖發(fā)布一個你根本不擁有的箱子，但恰好有一個團隊，你可能也會看到這個錯誤。

如果你改變主意，或者只是不確定是否crates.io有足夠的許可，你可以隨時去https://crates.io/login查看，crates.io會提示您，它沒有獲得它想要的所有范圍許可。

查詢 GitHub 的另一個障礙，是組織可能會主動拒絕第三方訪問。要檢查這一點，您可以訪問:

https://github.com/organizations/:org/settings/oauth_application_policy

這里的:org是組織的名稱(例如 rust-lang)。你可能會看到類似的東西:

你可以選擇，從您組織的黑名單中，明確刪除crates.io，或只需按"刪除限制(Remove Restrictions)"按鈕，允許所有第三方應用程序訪問此數(shù)據(jù)。

或者，當crates.io請求了read:org范圍，您可以明確進入白名單的crates.io，能查詢組織的問題，通過按其名稱旁邊的"授予訪問權限(Grant Access)"按鈕: