# 发版流程

发布一个新版本要做的事，按顺序来，漏一步就会出现"标签指向旧代码"或"附件与源码不一致"。

## 前置检查

```bash
# 工作区必须干净
git status --short

# 测试通过
node test-client.mjs        # 若本地有测试脚本
```

## 1. 改版本号

只有一处需要改：`package.json` 的 `version`。

面板显示的版本来自宿主 `/ping`，宿主读的是这个字段，不存在第二个地方。

## 2. 更新 CHANGELOG

在 `CHANGELOG.md` 顶部加一节，写清新增、修改、修复。

## 3. 提交并推送

```bash
git add -A
git commit -m "chore: 发布 vX.Y.Z"
git push
```

**先推送再打标签**。反过来会出现标签指向旧提交，之后要删除 Release 重来。

## 4. 打标签

```bash
git tag -a vX.Y.Z -m "vX.Y.Z"
git push origin vX.Y.Z
```

## 5. 建 Release

```bash
gh release create vX.Y.Z --title "vX.Y.Z" --notes-file CHANGELOG.md
```

或在 GitHub 网页上 `Releases → Draft a new release`，选标签、贴 CHANGELOG 对应小节。

正文里必须包含**安装说明**（三种方式：附件、clone、npm），否则下载附件的人不知道下一步做什么。

## 6. 打包附件

两个附件，内容相同、用途不同：

| 文件 | 生成方式 | 用途 |
|---|---|---|
| `dsh-media-X.Y.Z.zip` | 按 `package.json` 的 `files` 收集后压缩 | 不想装 git 的人 |
| `dsh-media-downloader-X.Y.Z.tgz` | `pnpm pack` | npm 风格安装 |

```bash
pnpm pack --pack-destination <输出目录>
```

**注意**：`files` 字段决定打进去哪些文件，新增目录（如 `docs/*.png`）要同步加进去，否则附件里会缺图。

## 7. npm 发布（可选）

```bash
npm publish --access public
```

前提：

- `package.json` 里**不能有** `private: true`
- 账号的 2FA 模式为 `auth-only`（`auth-and-writes` 会要求一次性验证码）

### 已知坑

1. **不要在发布前临时改 2FA 设置**。npm 会把「修改安全设置」判定为敏感操作，导致账号进入临时冻结，发布返回 `403 temporarily suspended`，通常要等数小时到 24 小时。
2. **npm 不提供 TOTP 验证器**了（设置页只有安全密钥）。如果账号处于 `auth-and-writes`，命令行发布就只能用**一次性恢复码**当 OTP——而恢复码等于账号钥匙，不适合传递。
3. 版本号一旦发布**不能覆盖**，只能发新版本。

## 8. 打完之后核对

- [ ] `git ls-remote --tags origin` 里标签指向最新提交
- [ ] Release 正文有安装说明
- [ ] 两个附件都在，且能下载
- [ ] 附件里的 `package.json` 版本号与标签一致
- [ ] README 里的徽章版本与实际一致