记创建并发布属于你自己的 rust crate

前言

创建部分就先略过，毕竟都能找到这儿了，这部分肯定熟。作者主要分享下如何通过 Github Actions 完成自动编译发布及其中可能的一些坑。

一. 前期准备

1. 不要重名!

是的，第一个要避免的就是先上 crates.io 搜搜看自己想出来的 crate name 别人有没有用了，如果有那很遗憾，改名吧！

2. 一个 crate repo

比如这里我们准备的这个 wincent-rs，至于它是干什么的，这不重要！

3. 一个 crates.io 账号

1. 访问 crates.io
2. 使用 GitHub 账号登录
3. 找到 Account Settings -> API Tokens
4. 点击 Create API Token
5. 记下这个 token，后面会用到

二. 更新 Crate

1. 更新项目信息

编辑 Cargo.toml，以下为示例：

[package]
name = "my-awesome-lib"
version = "0.1.0" # 每个发布版本版本号都需唯一，可失效，不可撤回
edition = "2021"
authors = ["Your Name <your.email@example.com>"]
description = "A brief description of your library"
license = "MIT"
repository = "https://github.com/username/my-awesome-lib"
documentation = "https://docs.rs/my-awesome-lib" # 使用 crate.io 自动生成的文档
readme = "README.md" # 即当前项目的 README.md, crates.io 会自动读取，但更新存在延迟
keywords = ["awesome", "library", "example"]
categories = ["development-tools"]

[dependencies]
# 添加依赖项

# 若 crate 文档中包含仅在 windows 下运行的代码，需添加以下部分避免 crates.io 自动编译文档出错
[package.metadata.docs.rs]
default-target = "x86_64-pc-windows-gnu"
targets = ["x86_64-pc-windows-gnu", "x86_64-pc-windows-msvc"]

2. 更新项目文档

编辑 README.md，以下为示例：

# My Awesome Library

A brief description of what your library does.

## Installation

Add this to your `Cargo.toml`:

````toml
[dependencies]
my-awesome-lib = "0.1.0"
````

## Usage

````rust
use my_awesome_lib::awesome_function;

fn main() {
    let result = awesome_function(42);
    println!("Result: {}", result);
}
````

## License

This project is licensed under the MIT License - see the LICENSE file for details.

生成并预览文档

cargo doc --no-deps --open # --no-deps 表示不生成依赖文档

三. GitHub Actions CI/CD 配置

1. 添加 Secrets

在 GitHub 仓库中配置必要的 secrets：

1. 访问仓库的 Settings -> Secrets and variables -> Actions -> Repository secrets
2. 添加新的 secret：
   • 名称：CARGO_REGISTRY_TOKEN
   • 值：你的 crates.io API token，这里就是之前生成的那个 token

2. 创建编译发布 Action

在项目根目录创建 .github/workflows/publish.yml：

name: Build and Publish

on:
  push:
    tags:
      - 'v*'

jobs:
  test:
    name: Test
    runs-on: windows-latest # 根据自己的 crate 选择合适的平台
    steps:
      - uses: actions/checkout@v4
      
      - name: Install Rust
        uses: dtolnay/rust-toolchain@stable
        with:
          toolchain: stable
      
      - name: Build
        run: cargo build --verbose
      
      - name: Run tests
        run: cargo test --verbose
      
      - name: Run clippy
        # clippy 会同时编译及运行函数文档中的 example，可以用 ```no_run 选择编译但不执行
        run: cargo clippy -- -D warnings 
      
      - name: Check formatting
        # 不是 M 不建议开这个，会检测格式是否正确，差不多就是 eslint，但是不能自动修复，纯纯折磨
        run: cargo fmt -- --check

  publish:
    name: Publish
    needs: test
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install Rust
        uses: dtolnay/rust-toolchain@stable
        with:
          toolchain: stable
      
      - name: Publish to crates.io
        shell: bash
        env:
          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
        run: cargo publish --token "$CARGO_REGISTRY_TOKEN"

3. 创建源码发布 Action

在项目根目录创建 .github/workflows/archive.yml：

name: Release Source Code

on:
  workflow_run:
    workflows: ["Build and Publish"]  # 监听 Build and Publish 工作流
    types:
      - completed
    branches: [ "main" ]

jobs:
  build:
    runs-on: windows-latest
    # 只在 Build and Publish 工作流成功时运行
    if: ${{ github.event.workflow_run.conclusion == 'success' && startsWith(github.event.workflow_run.head_branch, 'v') }}

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          ref: ${{ github.event.workflow_run.head_branch }}  # 检出对应的标签版本

      - name: Upload Release Assets
        uses: softprops/action-gh-release@v1
        with:
          tag_name: ${{ github.event.workflow_run.head_branch }}
          draft: true
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

这样当我们在 main 分支上创建新的 tag 时，会自动触发工作流，并发布到 crates.io，同时将源码打包发布至 Github Release。

记得手动更新 cargo.toml 中版本号！！作者暂时没想到什么特别好的方法自动升级并不报错通过 workflow。

git commit -m "Bump version to x.y.z"

# 3. 创建新的版本标签
git tag v0.1.0
git push origin v0.1.0

四. 总结

这是作者目前初步探索出来的一套方案，尚待优化，希望对你有所帮助