# 发布软件包

从已经完成版本修改的清单和变更日志重新建立发布执行计划，再按依赖关系发布软件包。

Source: https://semifold.noctisynth.org/zh/docs/commands/publish/
Language: zh



`smif publish` 面向版本与变更日志修改已经存在的软件包。它不依赖 `version` 已经消费的变更集。

```bash
smif publish --dry-run
smif publish
```

启用生成的 GitHub Actions 后，合入准备好的发布拉取请求会通过 [`smif ci`](https://semifold.noctisynth.org/zh/docs/commands/ci/) 触发推荐的发布路径。同一次发布不要再从本地重复执行。

## 规划与发布前检查 [#规划与发布前检查]

Semifold 读取当前清单与变更日志，通过工作区图排列软件包，展开配置命令，并在启动发布命令前执行所有可用的软件包仓库检查。缺少变更日志、已经存在的版本和软件包策略都会成为明确的跳过原因。

私有软件包只跳过软件包仓库预检和发布命令。有效的私有状态优先采用软件包级 `publish`，缺省时才采用清单或插件发现结果。私有软件包默认不创建 GitHub Release；显式配置 `github-release = true` 并启用 `--github-release` 时，仍会创建 Release 和上传附件。只有没有任何代码托管平台工作需要执行时，最终状态才会显示为私有软件包跳过。

HTTP 检查把 `200` 视为版本存在、`404` 视为不存在，其他状态码会安全失败。命令检查使用配置的 JSON Lines 契约。

## 执行 [#执行]

对于符合条件的软件包，Semifold 按依赖顺序运行发布前命令和发布命令。最终报告分别列出成功、跳过、失败和尚未开始的软件包，让部分失败可以基于事实重试。

| 选项                 | 行为                                        |
| ------------------ | ----------------------------------------- |
| `--dry-run`        | 运行只读检查，跳过软件包仓库与代码托管平台修改；只有明确允许预演的配置命令会执行。 |
| `--allow-dirty`    | 接受当前工作区差异作为有意的发布输入。                       |
| `--github-release` | 创建配置的 GitHub Release 并上传附件；只能在持续集成中使用。    |

如果软件包仓库中已经存在目标版本，对应发布命令会被跳过。启用 GitHub Release 后，Semifold 仍可补建缺失的 Release；已经存在的 Release 不会重新上传缺失附件。

## GitHub 错误诊断 [#github-错误诊断]

GitHub 操作失败时会显示失败操作、HTTP 状态、API 消息，以及可用的校验详情和文档链接。客户端错误保留底层错误链。这些信息无需开启 `--debug`，GitHub token 会被遮蔽。403 会按操作提供权限检查提示，但不会将原因一律断定为权限不足。

创建 Release 或上传附件失败时，保留对应包、失败阶段、部分发布报告和恢复指引。Release 已存在时仍按既有幂等逻辑跳过。