Publicando no crates.io
Publicar um crate no crates.io o torna disponível para o ecossistema via cargo add. O sucesso requer metadados corretos, disciplina semver e uma execução limpa de cargo package em modo de teste.
Receita
cargo publish --dry-run
cargo package --list
cargo login # token único
cargo publish[package]
license = "MIT OR Apache-2.0"
description = "Resumo curto"
repository = "https://github.com/you/crate"Quando usar isso: Compartilhar uma biblioteca além do seu workspace ou abrir código Rust reutilizável.
Exemplo de Trabalho
Prepare e publique a versão 0.2.0:
[package]
name = "valid-types"
version = "0.2.0"
edition = "2024"
rust-version = "1.97"
license = "MIT OR Apache-2.0"
description = "Newtypes para identificadores de domínio"
repository = "https://github.com/acme/valid-types"
readme = "README.md"
keywords = ["newtype", "validation"]
categories = ["development-tools"]
[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]cargo test --all-features
cargo doc --no-deps
cargo publish --dry-run
cargo publishO que isso demonstra:
- Metadados legais e de descoberta necessários para o crates.io
- Metadados
docs.rsconstroem a documentação com todos os recursos - O modo de teste (dry run) captura erros de empacotamento antes do upload
- O aumento semver reflete as mudanças na API desde
0.1.0
Mergulho Profundo
Checklist Pré-Publicação
| Etapa | Comando |
|---|---|
| Testes aprovados | cargo test --all-features |
| Clippy limpo | cargo clippy -- -D warnings |
| Documentação compila | cargo doc --no-deps |
| Arquivo tarball estável | cargo package --list |
| Arquivos de licença presentes | LICENSE-MIT, LICENSE-APACHE |
Política de Versionamento
0.y.z- trate o minorycomo quebra de compatibilidade para crates pré-1.0 (convenção do ecossistema)1.0.0- promessa de API estável; mudanças que quebram a compatibilidade exigem um aumento major- Entrada no Changelog para cada publicação (formato Keep a Changelog)
yank vs delete
cargo yank --version 0.1.1yankimpede novas resoluções; lockfiles existentes ainda podem usá-lo- A exclusão não é suportada; publique um release de patch em vez disso
Armadilhas
- Arquivo LICENSE ausente - publicação rejeitada. Correção: inclua arquivos SPDX que correspondam ao campo
license. - Publicando dependências de caminho - crates.io rejeita
path = "../...". Correção: publique as dependências primeiro ou use apenas dependências de versão. - Mudança que quebra compatibilidade em um patch - builds downstream quebram a confiança. Correção: siga o semver; use
cargo-semver-checksem CI para bibliotecas. - Pacote enorme de
target/ou dados - useexcludeemCargo.toml. Correção: revisão decargo package --list. - Token no histórico do shell - use
cargo logininterativo ou segredo de CICARGO_REGISTRY_TOKEN.
Alternativas
| Alternativa | Use Quando | Não Use Quando |
|---|---|---|
| Registro privado | Apenas crates internos | Crates do ecossistema open-source |
| Dependência Git | Consumidores pré-release | API pública estável |
cargo install do git | Ferramentas CLI, não bibliotecas | Código de biblioteca reutilizável |
FAQs
Posso despublicar?
A política do crates.io desencoraja a exclusão. Use yank em versões ruins e publique correções.
Como publico um membro de workspace?
Execute cargo publish -p nome_do_crate a partir da raiz do workspace; certifique-se de que as dependências de caminho foram publicadas ou substituídas por dependências de versão.
Qual o escopo do token do crates.io?
Use tokens com escopo para CI (apenas publicação, crates limitados) em vez de tokens de conta completos.
Como o docs.rs é acionado?
Automaticamente ao publicar. Configure [package.metadata.docs.rs] para recursos e --cfg docsrs para atributos de documentação.
Devo publicar 0.1.0 ou 1.0.0?
Comece com 0.1.0 enquanto a API estiver em evolução; mude para 1.0.0 quando você se comprometer com semver estável.
Como testo o crate empacotado?
cargo package e depois cargo install --path target/package/nome-versao.crate em um projeto temporário.
E os nomes de crates reservados?
Existe uma política de transferência para disputas de ocupação indevida; escolha nomes únicos cedo com cargo search.
Posso publicar binários?
crates.io é para bibliotecas; distribua CLIs via cargo install seu-cli após publicar o crate com um [[bin]].
Com que frequência devo lançar?
Quando correções ou recursos significativos forem lançados; evite lançamentos de rotina sem entradas no changelog.
O publish executa testes?
Não. A CI deve controlar cargo publish com cargo test e clippy aprovados.
Relacionado
- Fundamentos do Cargo -
cargo new --lib - Cargo.toml Explicado - campos de metadados
- Gerenciamento de Dependências - atualizações pós-publicação
- Boas Práticas do Cargo - higiene de release
Versões da Pilha: Esta página foi escrita para Rust 1.97.0 (edição 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4 e Polars 0.46+.