# 发布物料（docs/release）

每次发版要贴到仓库 Release 里的几样东西。体积十几个 G 的整包不适合直传，所以走「说明文档 + 网盘快捷方式」的组合。

| 文件 | 用途 |
|------|------|
| `publish_release.py` | **远程发版脚本**：校验 tag → 建/更新 Release → 上传附件（见下） |
| `发布说明模板.md` | Release 正文模板：本次更新、下载表格、安装步骤、说明 |
| `网盘下载.url` | Windows 网络快捷方式，双击直接打开网盘页面；作为附件上传 |

## 一条命令发版（推荐）

Gitea 的 Release 全流程都能走 REST API，不用点网页。脚本只用 Python 标准库，不需要装任何依赖。

```bash
# 1) token 放环境变量（只对当前窗口有效，别写进 .bat 提交上去）
set GITEA_TOKEN=xxxxxxxxxxxxxxxx

# 2) 先干跑：只打印计划，不产生任何写操作
python docs/release/publish_release.py --version v2026.11.06 --dry-run

# 3) 正式发（说明正文从模板读）
python docs/release/publish_release.py --version v2026.11.06 --notes-file docs/release/发布说明模板.md
```

它按六步走，任何一步不对就停下，不会留下半个 Release：

| 步骤 | 做什么 | 失败是否中止 |
|---|---|---|
| 1 | 解析本地 tag，与远端 tag 双向比对指向的提交 | **是** |
| 2 | 读说明正文（`--notes-file` 优先，其次 `--notes`） | — |
| 3 | 该 tag 已有 Release 就更新，没有就创建 | **是** |
| 4 | 检查附件；`.url` 里若还是 `REPLACE_WITH_YOUR_LINK` 就拒绝 | **是** |
| 5 | 上传附件；同名先删再传，**可以反复执行** | **是** |
| 6 | 回读自检（附件清单、是否草稿），打印 `html_url` | — |

常用参数：

```bash
--draft                  # 先存草稿（网页上只有自己可见），确认后去掉 --draft 重跑即转正式
--prerelease             # 标记预发布
--expect-commit 3b240ec  # 强制要求 tag 指向该提交，比默认更严
--asset 某个文件          # 可重复；默认只传 docs/release/网盘下载.url
--no-asset               # 只发说明，不传附件
--insecure               # 自签证书的内网 Gitea 才需要
--api / --repo           # 换服务器或换仓库时用
```

**为什么第 1 步要卡 tag**：2026.11.05 发版时，Release 挂着的 tag 指向一个**落后 12 个提交**的旧提交，源码包于是是旧代码，从网页上完全看不出来。脚本现在把这件事挡在发版之前，`--expect-commit` 还能多加一道。

> 实测记录（2026-11-05）：临时 tag 跑完整流程，创建 `201` → 上传 `201` → 下载 `200`（拿到正确的 `.url` 内容）→ 重复执行只保留一个同名附件 → 删除干净。字段名必须是 `attachment`，用 `file` 会返回 `500 http: no such file`。

## 手工发版（不想用脚本时）

1. 复制 `发布说明模板.md` 的内容到 Release 描述，按本次改动填「本次更新」
2. 核对下载链接：模板里的下载表格已填当前百度网盘地址与提取码，换盘或重新分享时同步替换
3. 若换了链接，同步改 `网盘下载.url`，让 `URL=` 与表格里的链接**完全一致**：

   ```ini
   [InternetShortcut]
   URL=https://pan.baidu.com/s/1j31dVPF_nPKSN2QYHU-Ygg?pwd=s33r
   IconIndex=0
   ```

   > 提取码已经拼进 `?pwd=`，双击打开后直接进目录，玩家不用再手输。

4. 附件区上传 `网盘下载.url`（注意：不是把整个网盘文件传上来）
5. 检查版本号与更新日志：`launcher/server.py` 的 `CURRENT_VERSION`、发布包根目录的 `更新日志.txt`
6. **确认 tag 指向**：`git log --oneline -1 v2026.11.xx` 与 `git ls-remote --tags origin` 里的 `^{}` 是同一个 sha

## 注意

- 仓库里的 `网盘下载.url` 现在指向**真实分享**（百度网盘，提取码 `s33r`）；重新分享会生成新链接，记得同步改 `.url` 与模板表格，避免玩家点开 404
- 传完自己双击验证一次，确认能打开网盘页面而不是 404
- token 只走环境变量 `GITEA_TOKEN` 或 `--token`，**不要**提交到仓库里的任何文件
- 发布包里 `Client\90CN.dll` 与 `Server\runtime\bin\DNF90Server.exe` 必须配套（DLL 指纹绑定），缺一个客户端就连不上