grid-npm-auto-publish/DEVELOPMENT.md

自动npm发布工具

# NPM包开发优化指南

## 问题分析

在开发业务时经常需要修改npm包，传统流程存在以下问题：
1. 本地开发调试困难
2. 每次修改都需要发布新版本
3. 发布流程复杂耗时
4. 版本管理混乱

## 解决方案

### 方案一：npm link（推荐用于本地开发）

#### 在npm包项目中：
```bash
# 1. 在npm包目录下创建全局链接
npm link grid-npm-auto-publish

# 2. 启动监听模式（如果有构建过程）
npm run watch
```

#### 在使用该npm包的项目中：
```bash
# 1. 链接到本地npm包
npm link grid-npm-auto-publish

# 2. 验证链接是否成功
npm ls grid-npm-auto-publish
```

#### 优势：
- ✅ 实时同步修改
- ✅ 无需发布即可测试
- ✅ 支持热重载
- ✅ 开发效率高

#### 注意事项：
- 记得在开发完成后取消链接：`npm unlink grid-npm-auto-publish`
- 确保两个项目的Node.js版本兼容

### 方案二：本地文件依赖

在业务项目的`package.json`中：
```json
{
  "dependencies": {
    "grid-npm-auto-publish": "file:../path/to/grid-npm-auto-publish"
  }
}
```

#### 优势：
- ✅ 简单直接
- ✅ 支持相对路径
- ✅ 适合临时调试

#### 缺点：
- ❌ 需要手动更新依赖
- ❌ 不支持热重载

### 方案三：Monorepo架构

使用Lerna或Nx管理多个包：

```bash
# 安装Lerna
npm install -g lerna

# 初始化monorepo
lerna init

# 添加包
lerna create package-name
```

#### 优势：
- ✅ 统一版本管理
- ✅ 依赖关系清晰
- ✅ 支持工作区
- ✅ 批量发布

### 方案四：快速发布脚本

使用我们提供的快速发布脚本：

```bash
# 快速发布补丁版本
node scripts/quick-release.js patch

# 快速发布次要版本
node scripts/quick-release.js minor

# 跳过测试快速发布
node scripts/quick-release.js patch --skip-tests
```

## 推荐工作流程

### 开发阶段
1. 使用 `npm link` 进行本地开发
2. 在业务项目中实时测试
3. 使用 `npm run watch` 监听文件变化

### 测试阶段
1. 取消链接：`npm unlink grid-npm-auto-publish`
2. 安装最新版本进行集成测试
3. 运行完整测试套件

### 发布阶段
1. 使用快速发布脚本：`node scripts/quick-release.js patch`
2. 等待GitHub Actions自动发布
3. 在业务项目中更新依赖版本

## 最佳实践

### 1. 版本管理
- 使用语义化版本控制
- 在README中记录变更日志
- 使用Git标签管理版本

### 2. 开发工具
- 配置ESLint和Prettier
- 使用TypeScript提供类型安全
- 编写单元测试和集成测试

### 3. 自动化
- 使用GitHub Actions自动发布
- 配置CI/CD流程
- 自动化测试和构建

### 4. 文档维护
- 保持README更新
- 提供使用示例
- 记录API变更

## 常见问题解决

### Q: npm link后修改不生效？
A: 检查是否有构建过程，确保运行了`npm run build`或`npm run watch`

### Q: 如何取消npm link？
A: 在使用该包的项目中运行：`npm unlink grid-npm-auto-publish`

### Q: 发布失败怎么办？
A: 检查GitHub Actions日志，确保NPM_TOKEN配置正确

### Q: 如何回滚版本？
A: 使用`npm version`命令回滚，然后重新发布

## 总结

通过以上方案，您可以：
1. 大幅提升开发效率
2. 简化发布流程
3. 减少版本管理复杂度
4. 提高代码质量

推荐使用 **npm link + 快速发布脚本** 的组合方案，既保证了开发效率，又简化了发布流程。