npmapps 1.0.26 → 1.0.28

package/PUBLISH.md

@@ -0,0 +1,268 @@
+# npmapps 发布流程
+
+> 本机作为「内网文件分发 / 跨设备搬运」工具的 npm 发布会话。包名 `npmapps`,基于公网 npmjs.org。每次发布照本流程做,5-10 分钟跑完。
+
+---
+
+## 0. 前置检查(30 秒)
+
+```bash
+cd /Users/wk/Documents/npmapps
+cat package.json | grep -E '"(name|version)"'
+npm config get registry
+```
+
+期望:
+- `name: "npmapps"`
+- `version: "1.0.<上次版本号>"`
+- `registry: https://registry.npmjs.org/`
+
+如果 `registry` 是内网,后面所有命令一致,只是发布目标不同。
+
+---
+
+## 1. 阶段 1:搬运源文件到 `app/`(2-5 分钟)
+
+### 1.1 搬整个文件夹(过滤 `node_modules`)
+
+```bash
+# 源
+SRC=/Users/wk/Documents/wk/web/wujie-wk/wujie-vue2-child
+
+# 目标
+DST=/Users/wk/Documents/npmapps/app
+
+# 同步(过滤 node_modules)
+rsync -a --exclude='node_modules' "$SRC/" "$DST/"
+
+# 删除原目录(完成"移动"语义)
+rm -rf "$SRC"
+
+# 验证:确认没漏
+du -sh "$DST"
+find "$DST" -type d -name node_modules   # 应该无输出
+```
+
+### 1.2 搬单个文件(zip / 压缩包 / 二进制)
+
+```bash
+mv /path/to/some.zip /Users/wk/Documents/npmapps/app/
+
+# 验证
+ls -la /Users/wk/Documents/npmapps/app/some.zip
+```
+
+### 1.3 验证 `app/` 状态
+
+```bash
+ls -la /Users/wk/Documents/npmapps/app
+```
+
+确认:
+- ✅ `wujie-vue2-child/` 子目录在(整个 Vue2 子应用)
+- ✅ `*.zip` 文件在
+- ✅ 没有 `node_modules`
+
+---
+
+## 2. 阶段 2:更新版本号(10 秒)
+
+```bash
+# 推荐用 npm 内置命令(自动修改 package.json)
+npm version patch   # 1.0.25 → 1.0.26
+# 其它选项:minor → 1.1.0,major → 2.0.0,具体版本号 → 1.0.27
+
+# 或者手动改 package.json
+#   "version": "1.0.25" → "1.0.26"
+
+# 验证
+grep '"version"' package.json
+```
+
+> ⚠️ 注意:`npm version` 默认会 `git commit` + `git tag`。这个项目不是 git 仓库所以没事。如果以后初始化了 git,加 `--no-git-tag-version` 防止自动 commit。
+
+---
+
+## 3. 阶段 3:预览(20 秒,发布前最后一道检查)
+
+```bash
+npm pack --dry-run
+```
+
+期望输出:
+```
+npm notice name: npmapps
+npm notice version: 1.0.26
+npm notice total files: 109 (大概)
+```
+
+**重点检查**:
+- ⚠️ 警告 `No .npmignore file found, using .gitignore` —— 这个项目外层没 `.gitignore`,npm 会读 `app/wujie-vue2-child/.gitignore`(嵌套目录的 gitignore npm 不读),所以 .codegraph、.DS_Store 之类的不会被自动排除
+- ⚠️ 出现 `app/.codegraph/daemon.pid` —— 这是本地 codegraph 索引 daemon 运行时残留文件,会进包。按需决定:
+  - 想干净:加 `.npmignore`(见附录 A)
+  - 无所谓:照发,166B 不影响
+
+---
+
+## 4. 阶段 4:处理 2FA / token(最容易卡住的环节)
+
+### 4.1 现状诊断
+
+```bash
+npm whoami            # 应该返回 npm 用户名
+npm profile get | grep "two-factor"
+```
+
+- `npm whoami` 返回用户名 ✅ token 有效
+- `two-factor auth: auth-and-writes` ❌ publish 会被 2FA 拦
+
+### 4.2 如果 `npm whoami` 401(token 失效)
+
+在终端跑(交互式):
+
+```
+! npm login
+```
+
+走 web flow:浏览器打开,登录授权,完成后 npm 自动把 token 写到 `~/.npmrc`。
+
+### 4.3 如果 publish 报 EOTP(2FA 拦下)
+
+**最快路径 —— 生成 bypass 2FA 的 token**:
+
+1. 浏览器打开 https://www.npmjs.com/settings/<用户名>/tokens
+2. **Generate New Token** → 名字随便(例如 `local-publish`)
+3. 类型选 **"Publish"**
+4. **关键:勾上 "Bypass two-factor authentication"** ⚠️ 这步必须勾,否则 publish 仍要 OTP
+5. 复制 token(`npm_xxxxxx...`)
+6. 替换 `~/.npmrc`:
+
+```bash
+# 备份 + 替换
+cp ~/.npmrc ~/.npmrc.bak
+# 编辑 ~/.npmrc,把 _authToken 那行的 token 换成新复制的
+```
+
+或者直接跑(把新 token 替换成你拿到的):
+
+```bash
+TOKEN=npm_xxxxxxxx
+sed -i '' "s|//registry.npmjs.org/:_authToken=.*|//registry.npmjs.org/:_authToken=$TOKEN|" ~/.npmrc
+
+# 验证
+npm whoami
+```
+
+### 4.4 替代方案:从账号层改 2FA 模式
+
+如果不想用 bypass token:
+1. 浏览器打开 https://www.npmjs.com/settings/<用户名>/security
+2. Two-Factor Authentication 改成 **"Authorization only"** 或 **Disabled**
+3. 保存(可能需要再输一次 OTP 或点邮件 magic link)
+4. 回来重试 publish
+
+---
+
+## 5. 阶段 5:真正发布(10 秒)
+
+```bash
+cd /Users/wk/Documents/npmapps
+npm publish
+```
+
+成功标志:
+
+```
++ npmapps@1.0.26
+```
+
+失败标志:
+- `EOTP`:回到阶段 4.3 换 bypass token
+- `E404: PUT ... npmapps`:token 失效,回到阶段 4.2
+- `ENEEDAUTH`:同上
+- `You do not have permission`:包名在公网被占,需要换名
+
+---
+
+## 6. 阶段 6:验证(10 秒)
+
+```bash
+# 1. 查公网版本列表
+npm view npmapps versions --json | tail -5
+# 期望看到刚发的版本
+
+# 2. 查发布时间戳
+npm view npmapps time --json | grep "<新版本号>"
+# 期望: "<新版本号>": "2026-..."
+
+# 3. 查 tarball 信息
+npm view npmapps dist
+# 期望:tarball URL 指向新版本
+```
+
+---
+
+## 7. 收尾(可选,2 分钟)
+
+```bash
+# 1. 清理 .npmrc 备份
+rm -f ~/.npmrc.bak
+
+# 2. 在 npm 网站 revoke 失效/过期的 token
+#    https://www.npmjs.com/settings/<用户名>/tokens
+#    只保留当前 .npmrc 里的那个,其余全 revoke
+
+# 3. 检查发布的 tarball 内容
+npm pack
+tar -tzf npmapps-<新版本号>.tgz | head -20
+# 看到不应该出现的文件就清理后再发新版本
+```
+
+---
+
+## 附录 A:加 `.npmignore` 让发布更干净(可选)
+
+如果想排除 `.codegraph`、`.DS_Store`、`package-lock.json`、`dist/` 等:
+
+```bash
+cat > /Users/wk/Documents/npmapps/.npmignore <<'EOF'
+.DS_Store
+.codegraph
+*.pid
+node_modules
+package-lock.json
+dist
+EOF
+```
+
+之后 `npm pack --dry-run` 会用这个文件,不再读 `.gitignore`。
+
+---
+
+## 附录 B:常用命令速查
+
+| 目的 | 命令 |
+|---|---|
+| 查包是否被占 | `npm view <name> name version` |
+| 查包全部元信息 | `npm view <name> --json` |
+| 查自己是谁 | `npm whoami` |
+| 查账号 2FA 模式 | `npm profile get` |
+| 生成 tarball(不发布) | `npm pack` |
+| 预览 tarball 内容 | `npm pack --dry-run` |
+| 登录 | `npm login`(交互) |
+| 登出 | `npm logout` |
+| 撤销发布(24 小时内) | `npm unpublish <pkg>@<version>` ⚠️ 慎用 |
+| deprecate 版本 | `npm deprecate <pkg>@<version> "msg"` |
+
+---
+
+## 附录 C:本次踩过的坑(避坑指南)
+
+| 坑 | 原因 | 解法 |
+|---|---|---|
+| `npm whoami` 401 | `~/.npmrc` 里 token 失效 | `npm login` 重新登录 |
+| publish E404 | 包名被占,token 无权覆盖 | 确认包归属 / 换名 / 用有 publish 权限的 token |
+| publish EOTP | 账号 `auth-and-writes` 2FA 模式 | 生成 **bypass 2FA** 的 token,或网站改 2FA 模式 |
+| tarball 里有 `.codegraph/` | 外层没 `.gitignore`/`.npmignore` | 加 `.npmignore`(附录 A),或接受 166B 的 daemon.pid 跟着发 |
+| `npm version` 自动 commit | 项目变成 git 仓库后 | 加 `--no-git-tag-version` 标志 |
+| `npmrc` 改了没生效 | 缓存 / 文件权限 | `cat ~/.npmrc` 确认;`chmod 600 ~/.npmrc` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "npmapps",
-  "version": "1.0.26",
+  "version": "1.0.28",
   "description": "",
   "main": "index.js",
   "scripts": {