sctj-components 1.0.0

package/PUBLISH_GUIDE.md

@@ -0,0 +1,293 @@
+# 组件库发布指南
+
+## 📋 发布前准备
+
+### 1. 检查组件依赖
+
+组件库已经处理了所有业务依赖：
+
+- ✅ **通用工具函数**（如 `generateShortId`、`getArrayLevel` 等）已打包进组件库
+- ✅ **业务 API 依赖**已改为通过 props 传入函数（如播放器组件）
+- ✅ **peerDependencies** 已配置，用户需要手动安装核心依赖
+- ✅ **静态资源**需要在宿主项目中手动拷贝（海康插件、BIM 插件）
+
+### 2. 更新 package.json
+
+发布前需要修改 `package.json` 中的以下字段：
+
+```json
+{
+  "name": "your-component-library-name",  // 修改为你的组件库名称
+  "version": "1.0.0",  // 设置初始版本
+  "description": "组件库描述",
+  "author": "你的名字"
+}
+```
+
+### 3. 处理样式文件
+
+如果组件使用了 SCSS，需要确保样式文件被正确打包。可能需要：
+
+1. 安装 `sass` 作为 devDependencies（已安装）
+2. 确保样式文件被正确引入
+
+## 🏗️ 构建组件库
+
+```bash
+# 构建组件库
+npm run build:lib
+```
+
+构建完成后，会在 `lib` 目录下生成：
+- `sctj-components.es.js` - ES 模块格式
+- `sctj-components.umd.js` - UMD 格式（浏览器直接使用）
+- `style.css` - 样式文件（如果有）
+
+## 📦 发布到 npm
+
+### 1. 登录 npm
+
+#### 方式一：标准登录（推荐）
+
+```bash
+npm login
+```
+
+系统会提示输入：
+- **Username**：你的 npm 用户名
+- **Password**：你的 npm 密码
+- **Email**：你的 npm 邮箱
+- **OTP**（如果启用了 2FA）：一次性验证码
+
+#### 方式二：Legacy 登录（使用 Access Token）
+
+如果你的 npm 账号启用了 2FA，或者需要使用 Access Token 登录，可以使用：
+
+```bash
+npm login --auth-type=legacy
+```
+
+**使用场景**：
+- 启用了 2FA 但想使用 token 登录
+- 需要使用 Granular Access Token（细粒度访问令牌）
+- CI/CD 自动化发布
+
+**操作步骤**：
+
+1. **获取 Access Token**：
+   - 访问：https://www.npmjs.com/settings/your-username/tokens
+   - 点击 "Generate New Token"
+   - 选择类型：
+     - **Automation**：用于 CI/CD，永久有效
+     - **Publish**：用于发布包，可设置过期时间
+   - 如果使用 Granular Access Token，需要启用 "Bypass 2FA" 权限
+   - 复制生成的 token（只显示一次，请妥善保存）
+
+2. **使用 token 登录**：
+   ```bash
+   npm login --auth-type=legacy
+   ```
+   
+   然后按提示输入：
+   - **Username**：你的 npm 用户名
+   - **Password**：**这里输入你的 Access Token（不是密码）**
+   - **Email**：你的 npm 邮箱（公开的邮箱地址）
+
+3. **验证登录**：
+   ```bash
+   npm whoami
+   ```
+   如果显示你的用户名，说明登录成功。
+
+#### 方式三：使用 .npmrc 配置 token（适合 CI/CD）
+
+如果不想交互式登录，可以直接在 `.npmrc` 文件中配置：
+
+```ini
+# 在项目根目录或用户目录的 .npmrc 文件中
+//registry.npmjs.org/:_authToken=your-access-token-here
+```
+
+**注意**：`.npmrc` 文件包含敏感信息，不要提交到 Git 仓库。
+
+#### 如果没有 npm 账号
+
+先注册：
+```bash
+npm adduser
+```
+
+或者访问：https://www.npmjs.com/signup
+
+### 2. 检查包名是否可用
+
+```bash
+npm view your-package-name
+```
+
+如果返回 404，说明包名可用。
+
+### 3. 更新版本号
+
+使用语义化版本号：
+
+```bash
+# 补丁版本 (1.0.0 -> 1.0.1) - 修复 bug
+npm version patch
+
+# 次版本 (1.0.0 -> 1.1.0) - 新功能，向后兼容
+npm version minor
+
+# 主版本 (1.0.0 -> 2.0.0) - 重大变更，不向后兼容
+npm version major
+```
+
+或者手动修改 `package.json` 中的 `version` 字段。
+
+### 4. 发布
+
+#### npm publish vs npm publish --tag beta
+
+**`npm publish`**（默认发布）：
+- 发布到 `latest` tag（默认 tag）
+- 用户执行 `npm install package-name` 时会安装这个版本
+- 适合稳定版本、正式版本
+
+**`npm publish --tag beta`**（带标签发布）：
+- 发布到 `beta` tag（或其他自定义 tag）
+- 用户需要明确指定 tag 才能安装：`npm install package-name@beta`
+- 适合测试版本、预发布版本、实验性功能
+
+**示例**：
+
+```bash
+# 发布正式版本（latest）
+npm publish
+# 用户安装：npm install sctj-components
+
+# 发布测试版本（beta）
+npm publish --tag beta
+# 用户安装：npm install sctj-components@beta
+
+# 发布预发布版本（alpha）
+npm publish --tag alpha
+# 用户安装：npm install sctj-components@alpha
+```
+
+**版本号与 tag 的关系**：
+
+```bash
+# 版本 1.0.0 发布为 latest（正式版）
+npm publish
+# → 用户 npm install 会得到 1.0.0
+
+# 版本 1.0.1-beta.1 发布为 beta（测试版）
+npm publish --tag beta
+# → 用户 npm install 不会自动安装，需要 npm install @beta
+
+# 版本 1.1.0 发布为 latest（新的正式版）
+npm publish
+# → 用户 npm install 会得到 1.1.0（自动更新）
+```
+
+**发布到私有 npm 源**：
+```bash
+npm publish --registry=https://your-registry-url
+```
+
+### 5. 验证发布
+
+```bash
+# 查看已发布的包
+npm view your-package-name
+
+# 安装测试
+npm install your-package-name
+```
+
+## 🔄 更新版本
+
+1. 修改代码
+2. 更新版本号：`npm version patch/minor/major`
+3. 构建：`npm run build:lib`
+4. 发布：`npm publish`
+
+## ⚠️ 常见问题
+
+### 1. 包名已被占用
+
+解决方案：
+- 更换包名
+- 使用 scope：`@your-username/package-name`
+
+### 2. 发布失败：需要认证或 2FA
+
+**错误信息**：
+```
+403 Forbidden - Two-factor authentication or granular access token with bypass 2fa enabled is required
+```
+
+**解决方案**：
+
+1. **启用 2FA**（推荐）：
+   - 访问：https://www.npmjs.com/settings/your-username/two-factor
+   - 启用双因素认证
+   - 使用 `npm login` 登录时会要求输入 OTP
+
+2. **使用 Granular Access Token**：
+   ```bash
+   npm login --auth-type=legacy
+   ```
+   - 创建 token 时启用 "Bypass 2FA" 权限
+   - 登录时在 Password 字段输入 token
+
+3. **检查当前登录状态**：
+   ```bash
+   npm whoami
+   ```
+
+### 3. 样式文件未打包
+
+检查 `vite.lib.config.js` 中的配置，确保样式文件被正确处理。
+
+### 4. 组件依赖的工具函数找不到
+
+组件库已将所有通用工具函数打包，如果遇到问题：
+- 检查 `vite.lib.config.js` 中的 `external` 列表
+- 确保工具函数在 `src/utils/index.js` 中正确导出
+
+### 5. 组件需要 API 函数但未提供
+
+部分组件（如播放器组件）需要通过 props 传入业务 API 函数，请参考 `README.md` 中的使用说明。
+
+## 📝 发布清单
+
+- [ ] 更新 `package.json` 中的包名、版本、描述等信息
+- [ ] 检查所有组件是否正常工作
+- [ ] 处理组件依赖的工具函数
+- [ ] 构建组件库：`npm run build:lib`
+- [ ] 检查 `lib` 目录下的文件
+- [ ] 测试安装和使用
+- [ ] 更新版本号
+- [ ] 发布到 npm
+
+## 🎯 使用私有 npm 源
+
+如果使用私有 npm 源（如公司内部源）：
+
+1. 配置 `.npmrc`：
+```
+registry=https://your-registry-url
+```
+
+2. 发布：
+```bash
+npm publish
+```
+
+## 📚 相关文档
+
+- [npm 发布文档](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry)
+- [语义化版本](https://semver.org/lang/zh-CN/)
+- [Vite 库模式](https://vitejs.dev/guide/build.html#library-mode)
+