@borurio-print/print-designer 1.0.7 → 1.0.9

package/README.md

@@ -104,27 +104,159 @@ i18n.global.mergeLocaleMessage('zh-cn', printDesignerZhCN)
 i18n.global.mergeLocaleMessage('en', printDesignerEnUS)
 ```
 
-## npm 发布
-
-首次发布前，需要确认当前 npm 账号拥有 `@borurio-print` 组织作用域的发布权限。先登录并检查
-即将进入安装包的文件：
-
-```bash
-npm login
-pnpm build:lib
-npm pack --dry-run
-```
-
-确认内容无误后发布公开包：
-
-```bash
-pnpm publish --access public
-```
-
-同一个版本号不能重复发布；后续修改需要先更新 `package.json` 中的版本号。
+## npm 发布
+
+包名和 npm registry 已在 `package.json` 中配置：
+
+- 包名：`@borurio-print/print-designer`
+- registry：`https://registry.npmjs.org/`
+- 公开范围：`public`
+- 发布前钩子：`prepublishOnly` 会自动执行 `pnpm build:lib`
+
+### 1. 检查本地和线上版本
+
+进入项目目录，确认当前工作区状态以及本地版本：
+
+```bash
+git status
+node -p "require('./package.json').version"
+```
+
+查询 npm 当前已经发布的版本：
+
+```bash
+npm view @borurio-print/print-designer version --registry=https://registry.npmjs.org/
+```
+
+同一个版本不能重复发布。如果本地版本与线上版本相同，先升级版本号：
+
+```bash
+pnpm version patch --no-git-tag-version
+```
+
+根据实际变更范围，也可以把 `patch` 换成 `minor` 或 `major`。如果上一次发布只是因为
+登录失效或权限不足而失败，并且线上还没有该版本，不要再次升级版本号。
+
+### 2. 检查 npm 登录和发布权限
+
+先检查当前 npm 登录状态：
+
+```bash
+npm whoami --registry=https://registry.npmjs.org/
+```
+
+如果返回 `E401 Unauthorized`，重新登录：
+
+```bash
+npm login --auth-type=web --registry=https://registry.npmjs.org/
+```
+
+登录成功后，再检查当前账号是否拥有该包的发布权限：
+
+```bash
+npm owner ls @borurio-print/print-designer --registry=https://registry.npmjs.org/
+```
+
+当前账号必须出现在 owner 列表中。如果不在，需要使用已有 owner 账号登录，或者由已有
+owner 为当前账号授予权限。
+
+### 3. 执行发布前构建和检查
+
+安装锁文件对应的依赖，并完整构建 Web 与 npm 两种产物：
+
+```bash
+pnpm install --frozen-lockfile
+pnpm build
+```
+
+检查 npm 包最终会包含哪些文件：
+
+```bash
+npm pack --dry-run
+```
+
+至少应确认以下文件存在：
+
+- `dist-lib/index.js`
+- `dist-lib/index.d.ts`
+- `dist-lib/style.css`
+- `dist-lib/PrintDesigner.vue.d.ts`
+- `dist-lib/core/types.d.ts`
+- `dist-lib/core/theme.d.ts`
+- `package.json`
+
+如果仓库跟踪 `dist-lib`，发布前应检查并提交最新构建产物。不要在存在来源不明的工作区
+改动时直接执行批量提交。
+
+### 4. 正式发布
+
+确认版本、账号、权限和打包内容无误后执行：
+
+```bash
+npm publish --access public --registry=https://registry.npmjs.org/
+```
+
+发布时会再次触发 `prepublishOnly`，自动执行 `pnpm build:lib`。终端出现下面格式的输出才
+表示上传成功：
+
+```text
++ @borurio-print/print-designer@1.0.7
+```
+
+`resolveComponent is imported ... but never used` 和 chunk size 属于构建警告，不等于发布
+失败；应以命令退出码和最后的 npm 发布结果为准。
+
+### 5. 发布后验证
+
+npm 新版本可能需要短暂处理时间。查询线上版本：
+
+```bash
+npm view @borurio-print/print-designer version --registry=https://registry.npmjs.org/
+```
+
+在临时目录或业务系统中安装明确版本进行验证：
+
+```bash
+npm install @borurio-print/print-designer@1.0.7
+```
+
+确认线上版本和业务系统验证正常后，再按团队 Git 流程提交版本变更并创建对应版本标签。
+
+### 常见发布错误
+
+#### `E401 Unauthorized`
+
+当前 npm 登录已失效。重新执行：
+
+```bash
+npm login --auth-type=web --registry=https://registry.npmjs.org/
+npm whoami --registry=https://registry.npmjs.org/
+```
+
+#### scoped 包发布时报 `E404 Not Found - PUT`
+
+对于已经存在的 scoped 包，这通常表示当前账号没有发布权限，或者认证信息已经失效，并不
+代表包真的不存在。依次检查：
+
+```bash
+npm whoami --registry=https://registry.npmjs.org/
+npm owner ls @borurio-print/print-designer --registry=https://registry.npmjs.org/
+npm view @borurio-print/print-designer version --registry=https://registry.npmjs.org/
+```
+
+如果 `npm whoami` 返回 `E401`，重新登录后再发布。如果账号不在 owner 列表中，需要切换
+到有权限的账号或申请权限。权限问题解决前不要继续递增版本号。
+
+#### 版本已经存在
+
+npm 不允许覆盖已经发布的相同版本。确认线上已经存在当前版本后，执行：
+
+```bash
+pnpm version patch --no-git-tag-version
+```
+
+重新构建、检查并发布新版本。
 
 ## 自动生成文件
 
-`src/auto-imports.d.ts` 和 `src/components.d.ts` 由自动按需引入插件生成；`pnpm-lock.yaml` 由 pnpm 生成。这些文件不应手动添加说明或修改内容。
-
-pnpm publish --access public
+`src/auto-imports.d.ts` 和 `src/components.d.ts` 由自动按需引入插件生成；`pnpm-lock.yaml` 由 pnpm 生成。这些文件不应手动添加说明或修改内容。