# npm 发布教程

本仓库发布单个公共 CLI 包 `@mingo_789/nas-deploy`。命令约定参考 mingo-ui-lib，使用 npm 和 package-lock.json，无 workspace 多包顺序问题。需要 Node.js 22+、npm 和本机 Bash，不需要 Docker 服务、NAS 或浏览器即可完成发布预演。

## 1. 首次准备

```bash
cd /path/to/nas-deploy
npm ci
npm run release:check
```

默认发布到 `https://registry.npmjs.org/`，访问权限 public。当前使用个人账号 `mingo_789` 对应的 `@mingo_789` scope；正式发布时使用该账号登录。若更换包名，同步 package.json、package-lock.json、安装示例和 AI 文档入口。

当前保留原有 `UNLICENSED` 标记，本次准备未变更项目许可。首次发布可以使用当前版本，不必先执行升版。

`release:check` 的实际流程：

1. 校验版本、锁文件和 publishConfig。
2. 执行语法检查和全部 Node 测试。
3. 打包到临时目录，检查运行文件、示例、README、AI 索引和按需文档是否完整，排除开发脚本、测试、环境文件和归档。
4. 在仓库外离线安装真实 `.tgz`，验证命令入口、版本、通用 init、dry-run 和文档相对链接，并确认归档不包含项目模板目录。
5. 输出 `artifacts/packages/<包名>-<版本>.tgz`、`artifacts/pack-check.json`，记录 SHA-512。
6. 对刚刚验收的同一归档执行 `npm publish --dry-run`，不会发布 npm，也不连接 NAS。

预演不要求登录，也不证明 scope 权限、版本可用性或发布认证已通过。`pack:check` 是相同的本地校验和归档验收，但不执行最后的 npm publish 预演。

## 2. 正式发布

仅在确实要上传 npm 时执行：

```bash
npm login --registry=https://registry.npmjs.org/
npm run release
```

`release` 先执行 npm whoami 检查登录，再运行完整验收，核对归档摘要，最后发布**已验收的压缩包**。它不会在发布阶段重新打包源码，也不会自动执行 Git 提交、Git tag、推送或 NAS 部署。发布命令继承终端输入输出，供 npm 需要时完成交互认证。

登录成功不等于具有该包的写权限。真实发布需满足 npm 的账号/组织权限和发布认证要求，具体以 npm 响应为准；认证方式见 [npm 发布认证说明](https://docs.npmjs.com/requiring-2fa-for-package-publishing-and-settings-modification/)。不要把 token 或恢复码写进仓库、脚本或对话。

## 3. 后续更新和预发布

```bash
npm run release:version             # 默认 patch
npm run release:check
npm run release
```

版本命令同时更新 package.json、package-lock.json 顶层版本和根 package 版本，不改其他依赖，不提交 Git。

| 命令 | 作用（当前为 0.1.0） |
| --- | --- |
| `npm run release:version` | 0.1.1 |
| `npm run release:version -- patch` | 0.1.1 |
| `npm run release:version -- minor` | 0.2.0 |
| `npm run release:version -- major` | 1.0.0 |
| `npm run release:version -- 0.2.3` | 显式指定 0.2.3 |

自动递增要求当前为稳定版本且锁文件版本一致；不一致或处于预发布版本时，用显式版本同步。显式输入支持 `0.2.0-beta.0`，不接受前导零或 build metadata。同步修改 [CHANGELOG](../CHANGELOG.md) 的版本说明。

```bash
npm run release:version -- 0.2.0-beta.0
npm run release:check -- --tag beta
npm run release -- --tag beta
```

稳定版本默认 `latest`，预发布默认 `next`。脚本拒绝把预发布版本标为 latest。npm run 后面的 `--` 必须保留，用于把 tag 参数传给脚本。

## 4. 失败后重试

- 语法、测试、隔离安装或摘要校验失败：修复问题后重新预演；不会进入发布步骤。
- 登录/权限/认证失败：在本机终端处理账号认证，然后重试，不要反复执行升版命令。
- 网络中断且不确定是否已发布：先用 `npm view @mingo_789/nas-deploy@<版本> dist.integrity --registry=https://registry.npmjs.org/` 查询，核对本次归档的 SHA-512（报告为 hex；registry 的 integrity 通常使用 `sha512-<base64>`）。
- 版本已经存在：不能覆盖。若内容需要修改，升新版本并重新走完整流程；不要删除旧版本试图复用版本号。

版本不可重复和 tarball 发布方式见 [npm publish 官方说明](https://docs.npmjs.com/cli/v10/commands/npm-publish/)。归档文件选择规则见 [npm pack 官方说明](https://docs.npmjs.com/cli/v10/commands/npm-pack/)。

## 5. 其他项目安装

成功发布之后，在使用方项目执行：

```bash
npm install --save-dev --save-exact @mingo_789/nas-deploy@0.1.0
# 或
pnpm add -D -E @mingo_789/nas-deploy@0.1.0
```

这里的版本应替换为实际发布版本。未发布时，可用 `artifacts/packages/*.tgz` 做本地接入验证；不要在团队锁文件中遗留个人电脑绝对路径。

安装后的人工教程在 [README](../README.md)，AI 从 [AGENT_GUIDE.md](../AGENT_GUIDE.md) 开始读取。