📦 vue-sdk-demo 完整发布指南

一个完全自包含的 Vue 3 SDK，主项目零配置，SDK 内部自动处理开发/生产模式切换。

✨ 特性

• 🎯 主项目零配置：主项目无需任何特殊配置，直接导入即可
• 🔄 SDK 内部自适应：通过命令自动切换开发/生产模式
• 🛠️ 开发友好：开发模式直接使用源码，支持热更新
• 🚀 生产优化：生产模式使用优化构建产物
• 🎨 样式自包含：CSS 自动处理，无需手动导入
• 📦 一键发布：完整的发布和更新流程自动化

🚀 快速开始

1. 主项目使用：

   import { name, add } from 'vue-sdk-demo';

2. SDK 开发：

   pnpm dev-mode   # 开发调试
   pnpm build      # 发布构建

完全不需要在主项目配置任何东西！🎉

📦 发布和更新流程

方式一：一键发布和更新（推荐）

这个命令会完成完整的发布流程：

1. 自动更新版本号（patch + 1）
2. 构建包
3. 发布到 npm
4. 更新 test-app 依赖
5. 重新启动 turbo 开发服务器

# 在 vue-sdk-demo 目录下执行
pnpm publish-and-update

方式二：快速本地更新

用于本地开发和测试，不发布到 npm：

1. 切换到开发模式
2. 更新 test-app 依赖
3. 重新启动 turbo 开发服务器

# 在 vue-sdk-demo 目录下执行
pnpm quick-update

方式三：手动流程

如果需要更精细的控制，可以手动执行每个步骤：

# 1. 开发模式（使用源码）
pnpm dev-mode

# 2. 构建和发布
pnpm build          # 构建并切换到构建产物模式
pnpm publish        # 发布到 npm

# 3. 更新 test-app
cd ../test-app
pnpm install        # 安装最新版本

# 4. 重新启动 turbo
cd ..
turbo dev           # 重新启动开发服务器

方式四：完全手动操作

如果不使用任何脚本，可以按照以下步骤手动操作：

发布新版本

# 1. 手动更新版本号
cd apps/vue-sdk-demo
# 编辑 package.json 中的 version 字段

# 2. 构建包
pnpm build

# 3. 发布到 npm
npm publish

# 4. 更新 test-app 依赖
cd ../test-app
pnpm install

# 5. 重启 turbo
cd ..
turbo dev

本地开发

# 1. 切换到开发模式
cd apps/vue-sdk-demo
pnpm dev-mode

# 2. 更新 test-app
cd ../test-app
pnpm install

# 3. 重启 turbo
cd ..
turbo dev

🔄 操作流程图

发布流程

graph TD
    A[开始] --> B[手动更新版本号]
    B --> C[执行 pnpm build]
    C --> D[检查 dist/ 目录]
    D --> E[执行 npm publish]
    E --> F[验证 npm 官网]
    F --> G[切换到 test-app]
    G --> H[执行 pnpm install]
    H --> I[重启 turbo dev]
    I --> J[测试功能]
    J --> K[完成]
    
    D --> D1{构建成功?}
    D1 -->|否| D2[检查构建配置]
    D2 --> C
    
    E --> E1{发布成功?}
    E1 -->|否| E2[检查 npm 登录]
    E2 --> E

开发模式流程

graph TD
    A[开始] --> B[执行 pnpm dev-mode]
    B --> C[验证 package.json]
    C --> D[切换到 test-app]
    D --> E[执行 pnpm install]
    E --> F[重启 turbo dev]
    F --> G[验证热更新]
    G --> H[完成]
    
    C --> C1{切换成功?}
    C1 -->|否| C2[手动检查配置]
    C2 --> B

📋 详细操作步骤

发布新版本

| 步骤 | 命令 | 说明 | 检查点 | |------|------|------|--------| | 1 | cd apps/vue-sdk-demo | 进入包目录 | 确认目录正确 | | 2 | 编辑 package.json | 更新 version 字段 | 版本号递增 | | 3 | pnpm build | 构建包 | dist/ 目录生成 | | 4 | npm publish | 发布到 npm | npm 官网显示 | | 5 | cd ../test-app | 切换到测试应用 | 确认目录正确 | | 6 | pnpm install | 更新依赖 | 版本号更新 | | 7 | cd .. | 回到根目录 | 确认目录正确 | | 8 | turbo dev | 重启开发服务器 | 服务正常运行 |

本地开发

| 步骤 | 命令 | 说明 | 检查点 | |------|------|------|--------| | 1 | cd apps/vue-sdk-demo | 进入包目录 | 确认目录正确 | | 2 | pnpm dev-mode | 切换到开发模式 | package.json 指向源码 | | 3 | cd ../test-app | 切换到测试应用 | 确认目录正确 | | 4 | pnpm install | 更新依赖 | 使用最新源码 | | 5 | cd .. | 回到根目录 | 确认目录正确 | | 6 | turbo dev | 重启开发服务器 | 热更新正常 |

🔧 脚本说明

| 脚本 | 功能 | 使用场景 | |------|------|----------| | pnpm dev-mode | 切换到开发模式 | 本地开发调试 | | pnpm build | 构建并切换到生产模式 | 准备发布 | | pnpm publish-and-update | 一键发布和更新 | 正式发布 | | pnpm quick-update | 快速本地更新 | 本地测试 |

📋 版本管理

• 开发模式：使用源码，支持热更新
• 生产模式：使用构建产物，优化性能
• 版本更新：自动递增 patch 版本号
• Catalog 版本：test-app 中使用 catalog: 版本，自动获取最新版本

🎯 工作流程

开发阶段

pnpm dev-mode        # 切换到开发模式
# 修改代码...
pnpm quick-update    # 快速更新到 test-app

发布阶段

pnpm publish-and-update  # 一键完成发布和更新

⚠️ 关键检查点

发布前检查

# 1. 版本号检查
cat apps/vue-sdk-demo/package.json | grep version

# 2. npm 登录检查
npm whoami

# 3. 构建产物检查
ls -la apps/vue-sdk-demo/dist/

# 4. git 状态检查
git status

发布后检查

# 1. npm 官网检查
npm view vue-sdk-demo version

# 2. test-app 依赖检查
cat apps/test-app/node_modules/vue-sdk-demo/package.json | grep version

# 3. turbo 状态检查
ps aux | grep turbo

开发模式检查

# 1. package.json 入口检查
cat apps/vue-sdk-demo/package.json | grep -E "(main|module|types)"

# 2. test-app 依赖检查
cat apps/test-app/package.json | grep vue-sdk-demo

# 3. 热更新检查
# 修改源码文件，观察浏览器是否自动刷新

🚨 常见错误处理

错误：版本号已存在

# 解决方案
npm view vue-sdk-demo versions
# 选择未使用的版本号
# 手动更新 package.json

错误：构建失败

# 解决方案
rm -rf apps/vue-sdk-demo/dist/
rm -rf apps/vue-sdk-demo/node_modules/.vite
cd apps/vue-sdk-demo
pnpm install
pnpm build

错误：依赖更新失败

# 解决方案
cd apps/test-app
rm -rf node_modules
pnpm install

错误：turbo 启动失败

# 解决方案
rm -rf .turbo
pkill -f "turbo dev"
turbo dev

💡 操作技巧

1. 使用别名简化操作

   # 添加到 ~/.zshrc 或 ~/.bashrc
   alias npmpub="cd apps/vue-sdk-demo && pnpm build && npm publish"
   alias npminst="cd apps/test-app && pnpm install"

2. 使用脚本片段

   # 发布流程片段
   cd apps/vue-sdk-demo && \
   pnpm build && \
   npm publish && \
   cd ../test-app && \
   pnpm install && \
   cd .. && \
   turbo dev

3. 使用 tmux 或 screen

   # 在多个终端窗口同时操作
   tmux new-session -d -s publish
   tmux split-window -h
   tmux send-keys -t 0 "cd apps/vue-sdk-demo" C-m
   tmux send-keys -t 1 "cd apps/test-app" C-m

📝 操作清单

发布清单

• [ ] 更新 package.json 版本号
• [ ] 执行 pnpm build
• [ ] 检查 dist/ 目录
• [ ] 执行 npm publish
• [ ] 验证 npm 官网
• [ ] 更新 test-app 依赖
• [ ] 重启 turbo 开发服务器
• [ ] 测试功能

开发清单

• [ ] 执行 pnpm dev-mode
• [ ] 更新 test-app 依赖
• [ ] 重启 turbo 开发服务器
• [ ] 验证热更新

⚠️ 注意事项

1. turbo dev 启动：脚本中的 turbo dev 启动已注释，需要手动运行
2. 版本号：发布时会自动递增 patch 版本号
3. 依赖更新：test-app 使用 catalog 版本，会自动获取最新版本
4. 权限：确保有 npm 发布权限
5. 网络：确保网络连接正常

🔍 故障排除

发布失败

• 检查 npm 登录状态：npm whoami
• 检查版本号是否已存在
• 检查网络连接

更新失败

• 检查 test-app 路径是否正确
• 检查 pnpm 是否正常工作
• 检查 turbo 配置是否正确

热更新不工作

• 确保使用 pnpm dev-mode 切换到开发模式
• 检查 test-app 是否正确安装了依赖
• 重启 turbo dev 服务器

💡 最佳实践

1. 版本号管理：使用语义化版本号（major.minor.patch）
2. 发布前测试：确保本地功能正常
3. 逐步验证：每个步骤都要验证结果
4. 备份重要文件：发布前备份 package.json
5. 记录操作日志：记录每次发布的操作步骤

🎯 使用场景

| 场景 | 命令 | 说明 | |------|------|------| | 正式发布 | pnpm publish-and-update | 发布到 npm，更新版本 | | 本地测试 | pnpm quick-update | 本地开发，不发布 | | 开发调试 | pnpm dev-mode | 切换到源码模式 |

📦 发布流程说明

1. 一键发布流程

• ✅ 自动更新版本号（patch + 1）
• ✅ 构建包
• ✅ 发布到 npm
• ✅ 更新 test-app 依赖
• ✅ 提示重启 turbo（需要手动执行）

2. 本地更新流程

• ✅ 切换到开发模式
• ✅ 更新 test-app 依赖
• ✅ 提示重启 turbo（需要手动执行）

🔧 重要提示

1. turbo dev 需要手动启动：脚本中的 turbo dev 启动已注释
2. 版本号自动递增：每次发布会自动 +1 patch 版本
3. catalog 版本：test-app 会自动获取最新版本
4. 权限检查：确保有 npm 发布权限

🔧 故障排除

• 发布失败：检查 npm whoami 登录状态
• 更新失败：检查 test-app 路径和 pnpm 配置
• 热更新不工作：确保使用 pnpm dev-mode 切换到开发模式