@viso/package-release

一个用于自动化项目发布和资源部署的工具，支持将构建产物整理到指定的发布目录结构中。

功能特性

• 🚀 自动化发布流程管理
• 📁 智能的目录结构生成
• 📦 支持多包类型和版本管理
• 🔄 自动复制构建产物和静态资源
• 🛡️ 安全的目录清理和创建
• 🎯 基于 package.json 的智能路径解析

安装

npm install @viso/package-release

使用场景

这个工具主要用于：

• 将项目的 dist/ 目录内容发布到指定的发布目录
• 将项目的 public/ 目录内容一同部署
• 基于包名和版本自动生成目录结构
• 清理旧版本文件并部署新版本

命令行使用

基本发布

# 发布到默认的 release 目录
npx package-release

# 发布到指定目录
npx package-release --target /path/to/deploy

生成的目录结构

假设项目 package.json 如下：

{
  "name": "@company/awesome-package",
  "version": "1.2.3"
}

执行发布后会生成以下目录结构：

release/
└── dist/
    └── company/           # 从包名提取的组织名
        └── awesome-package/   # 从包名提取的包名
            └── 1.2.3/         # 版本号目录
                ├── index.js   # 来自 dist/ 目录
                ├── style.css  # 来自 dist/ 目录
                └── assets/    # 来自 public/ 目录

API 使用

release

执行发布操作：

import { release } from '@viso/package-release'

// 发布到指定目录
await release(process.cwd(), '/path/to/target')

// 发布到相对目录
await release('/path/to/project', 'release')

参数说明

• rootDir: 项目根目录路径
• targetDir: 发布目标目录路径

目录结构解析

工具会根据 package.json 中的包名自动解析目录结构：

包名解析规则

| 包名 | 提取的类型 | 提取的路径 | 生成的目录 | |------|------------|------------|------------| | @company/package-name | company | package-name | dist/company/package-name/ | | package-name | null | package-name | dist/package-name/ | | @scope/sub/package | scope | sub/package | dist/scope/sub/package/ |

版本目录

• 如果 package.json 中有 version 字段，使用版本号作为目录名
• 如果没有 version 字段，使用 latest 作为目录名

复制的内容

工具会自动复制以下目录的内容：

dist/ 目录

项目构建后的产物，包括：

• JavaScript 文件
• CSS 文件
• 源码映射文件
• 其他构建产物

public/ 目录（可选）

静态资源文件，包括：

• 图片、字体等资源文件
• 配置文件
• 其他静态内容

目录清理策略

发布过程中的清理行为：

1. 父目录处理：

   • 如果父目录不存在，自动创建
   • 如果父目录已存在，清空父目录内容

2. 版本目录处理：

   • 如果版本目录不存在，自动创建
   • 保留版本目录的完整性

集成到构建流程

在 package.json 中添加脚本

{
  "scripts": {
    "build": "package-build --dist",
    "release": "npm run build && package-release",
    "release:prod": "npm run build && package-release --target /var/www/releases"
  }
}

与 CI/CD 集成

# GitHub Actions 示例
- name: Build and Release
  run: |
    npm run build
    npx package-release --target ./releases
    
- name: Deploy to Server
  run: |
    rsync -av ./releases/ user@server:/var/www/

使用示例

基本发布流程

import { release } from '@viso/package-release'
import { readPackageJson } from '@viso/package-utils'

async function deployProject() {
  const rootDir = process.cwd()
  const packageJson = await readPackageJson(rootDir)
  
  console.log(`Releasing ${packageJson?.name}@${packageJson?.version}`)
  
  // 发布到生产环境目录
  await release(rootDir, '/var/www/releases')
  
  console.log('Release completed!')
}

deployProject()

多环境发布

import { release } from '@viso/package-release'

async function deployToEnvironments() {
  const rootDir = process.cwd()
  
  // 发布到测试环境
  await release(rootDir, './releases/staging')
  
  // 发布到生产环境
  await release(rootDir, './releases/production')
}

错误处理

• 如果找不到 package.json 文件，会抛出错误
• 如果源目录（dist/、public/）不存在，会跳过相应的复制操作
• 目录创建和文件复制失败时会抛出详细的错误信息

依赖项

• @viso/package-utils: 包工具函数（包名解析、package.json 读取）
• commander: 命令行参数解析
• fs-extra: 增强的文件系统操作

许可证

本项目使用 MIT 许可证。