atchain-mapbox-vue/PUBLISH_CHECKLIST.md

A Vue 3 MapBox component library with subway lines, stations, markers and polygons support. Zero dependencies except Vue 3 and Mapbox GL JS.

# 📋 NPM 发布检查清单

在发布到 npm 之前，请确保完成以下所有检查项：

## 🔧 发布前准备

### 1. 账号和权限
- [ ] 已注册 npm 账号 (https://www.npmjs.com/signup)
- [ ] 已验证邮箱地址
- [ ] 已登录 npm (`npm login`)
- [ ] 确认包名可用 (`npm view atchain-mapbox-vue`)

### 2. 包信息配置
- [ ] 更新 `package.json` 中的个人信息：
  - [ ] `name`: 已设置为 `atchain-mapbox-vue`
  - [ ] `author.name`: 你的真实姓名
  - [ ] `author.email`: 你的邮箱
  - [ ] `author.url`: 你的网站（可选）
  - [ ] `repository.url`: 你的 GitHub 仓库地址
  - [ ] `homepage`: 项目主页地址
  - [ ] `bugs.url`: Issues 页面地址

### 3. 版本管理
- [ ] 确认当前版本号合理 (`package.json` 中的 `version`)
- [ ] 更新 `CHANGELOG.md` 记录本次发布的变更
- [ ] 确保版本遵循 [语义化版本](https://semver.org/) 规范

### 4. 文档完整性
- [ ] `README.md` 内容完整且准确
- [ ] `QUICK_START.md` 示例可运行
- [ ] `CHANGELOG.md` 记录了所有重要变更
- [ ] `LICENSE` 文件存在且正确
- [ ] API 文档完整

### 5. 代码质量
- [ ] 所有 TypeScript 类型定义正确
- [ ] 没有 console.log 等调试代码
- [ ] 代码格式统一
- [ ] 移除了开发时的临时文件

## 🧪 测试验证

### 6. 功能测试
- [ ] 所有组件正常工作
- [ ] 交互功能正常（点击、悬停）
- [ ] 数据加载正常
- [ ] 样式显示正确
- [ ] 在不同浏览器中测试

### 7. 集成测试
- [ ] 在新的 Vue 3 项目中测试安装和使用
- [ ] 验证 TypeScript 类型提示正常
- [ ] 验证 Tree Shaking 工作正常
- [ ] 测试不同的导入方式

## 📦 包配置检查

### 8. 文件包含
- [ ] 检查 `files` 字段包含所有必要文件
- [ ] 检查 `.npmignore` 排除不必要文件
- [ ] 运行 `npm pack --dry-run` 查看包内容
- [ ] 确认包大小合理

### 9. 依赖配置
- [ ] `peerDependencies` 版本范围合理
- [ ] 没有不必要的 `dependencies`
- [ ] `devDependencies` 不会被安装到用户项目

### 10. 导出配置
- [ ] `main` 字段指向正确的入口文件
- [ ] `types` 字段指向类型定义文件
- [ ] `exports` 字段配置正确
- [ ] 支持 ESM 和 CommonJS

## 🚀 发布执行

### 11. 发布前最后检查
- [ ] 运行 `npm run prepublishOnly` 通过
- [ ] 本地构建成功
- [ ] Git 工作区干净（所有更改已提交）
- [ ] 在正确的分支上（通常是 main/master）

### 12. 执行发布
```bash
# 方式1: 使用脚本（推荐）
./scripts/publish.sh

# 方式2: 手动发布
npm publish
```

### 13. 发布后验证
- [ ] 在 npm 官网确认包已发布
- [ ] 版本号正确
- [ ] 包信息显示正确
- [ ] 在新项目中测试安装：`npm install atchain-mapbox-vue`

## 📢 发布后工作

### 14. 宣传和维护
- [ ] 创建 GitHub Release
- [ ] 更新项目 README 添加安装说明
- [ ] 在社交媒体或技术社区分享
- [ ] 准备回应用户反馈和问题

## ⚠️ 常见问题

### 包名冲突
如果包名已存在，尝试：
- 使用 scoped 包名：`@your-username/package-name`
- 添加后缀：`package-name-vue3`
- 使用更具描述性的名称

### 发布失败
常见原因：
- 未登录 npm
- 包名已存在
- 版本号重复
- 网络问题

### 版本管理
- 补丁版本：`1.0.1` (bug 修复)
- 次版本：`1.1.0` (新功能，向后兼容)
- 主版本：`2.0.0` (破坏性变更)

---

✅ **完成所有检查项后，你就可以安全地发布到 npm 了！**