build-deploy-tools

Build Deploy Tools

🚀 构建部署工具包 - 一个功能强大的 Node.js 工具包，提供文件复制、SVN 操作、系统通知确认等功能，具有科技感进度条和现代化UI，专为自动化构建部署流程设计。

✨ 主要特性

• 🎆 科技感进度条 - 全新的现代化进度显示界面，多种主题色彩和动态效果
• 🚀 智能多阶段进度 - SVN操作分解为多个阶段，实时显示每个步骤的进度
• 🔄 智能重试机制 - 自动处理网络异常和临时错误
• 📢 跨平台通知 - 支持 Windows、macOS、Linux 系统通知
• 🤖 自动化模式 - 支持 CI/CD 环境的无人值守操作
• 📁 文件操作 - 高效的文件复制、删除等操作
• 🔗 SVN 集成 - 完整的 SVN 更新、提交、删除等操作
• 🧠 智能提交信息 - 自动从Git/SVN获取最近提交信息，支持自定义格式化
• 🎨 现代化UI - 渐变色文字、动态动画、实时ETA显示
• 🛠️ 命令行工具 - 提供便捷的 CLI 命令
• 📝 详细日志 - 完整的操作日志和错误信息

📦 安装

全局安装（推荐）

npm install -g build-deploy-tools

项目本地安装

npm install build-deploy-tools --save-dev

临时使用

npx build-deploy-tools --help

🚀 快速开始

命令行使用

1. 文件复制工具

# 交互模式（默认）
build-copy

# 自动模式
build-copy --auto

# 自动模式 + 自动提交 SVN
build-copy --auto --commit

# 自定义构建文件名、源目录和目标目录
build-copy --build=myapp --source=./dist --target=D:/Projects/deployment

# 使用环境变量配置
TARGET_DIR=D:/Projects/deployment BUILD_NAME=myapp build-copy --auto

# 或使用 .env 文件（推荐）
# 1. 安装 dotenv: npm install dotenv
# 2. 复制 env.example 为 .env 并编辑
# 3. 直接运行: build-copy

# 🆕 使用智能提交信息（v1.3.0+）
build-copy --auto --commit  # 自动获取Git/SVN最近提交信息

# 🆕 自定义提交信息
build-copy --message="修复登录问题" --commit

# 🆕 格式化提交信息
build-copy --prefix="🚀" --add-timestamp --commit

2. 通知功能测试

# 测试系统通知功能
test-notification

# 自动模式测试
test-notification --auto

编程方式使用

const { BuildDeployTools } = require('build-deploy-tools')

// 创建工具实例
const tools = new BuildDeployTools({
  maxRetries: 3,
  retryDelay: 2000
})

// 执行构建复制
async function deploy() {
  try {
    await tools.executeBuildCopy({
      sourceDir: './dist',
      targetParentDir: 'D:/Projects/deployment',
      fileName: 'myapp',
      autoCommit: true,
      // 🆕 v1.3.0+ 智能提交信息功能
      useVcsHistory: true,  // 启用版本控制历史
      commitMessage: null,  // 使用智能获取的信息
      commitOptions: {
        prefix: '[自动部署]',
        addTimestamp: true
      }
    })
    console.log('部署成功！')
  } catch (error) {
    console.error('部署失败:', error.message)
  }
}

📚 快速配置

.env 文件配置（推荐）

最简单的方式是使用 .env 文件：

# 1. 安装 dotenv
npm install dotenv

# 2. 复制示例文件
cp env.example .env

# 3. 编辑 .env 文件
# TARGET_DIR=D:/Work/Vue3/myproject
# BUILD_NAME=myapp
# AUTO_MODE=true
# AUTO_COMMIT=true

# 4. 使用
build-copy

package.json 集成

{
  "scripts": {
    "build": "vite build",
    "deploy": "npm run build && build-copy --auto",
    "deploy-commit": "npm run build && build-copy --auto --commit",
    "test-notification": "test-notification"
  },
  "devDependencies": {
    "build-deploy-tools": "^1.5.0"
  }
}

使用示例

# 构建并手动确认部署
npm run deploy

# 自动构建部署并提交
npm run deploy-commit

# 测试通知功能
npm run test-notification

🔧 构建工具集成

方案1：Webpack 集成（推荐）

在 vue.config.js 或 webpack.config.js 中配置：

const { BuildDeployTools } = require('build-deploy-tools')

// 检查是否应该执行部署插件
function shouldExecuteDeployPlugin() {
  // 只有包含 'build-copy' 的npm脚本才执行插件
  const scriptName = process.env.npm_lifecycle_event || ''
  const scriptCommand = process.env.npm_lifecycle_script || ''
  
  console.log(`🔍 当前npm脚本: ${scriptName}`)
  console.log(`🔍 脚本命令: ${scriptCommand}`)
  
  // 检查脚本名称或命令中是否包含 build-copy
  const shouldExecute = scriptName.includes('build-copy') || 
                       scriptCommand.includes('build-copy') ||
                       scriptName.includes('deploy')
  
  console.log(`🔍 是否执行部署插件: ${shouldExecute}`)
  return shouldExecute
}

module.exports = {
  // ... 其他配置
  configureWebpack: {
    plugins: [
      // 在生产环境下创建自定义插件，在构建完成后执行复制操作
      process.env.NODE_ENV === 'production' && shouldExecuteDeployPlugin()
        ? {
            apply: compiler => {
              // 使用webpack的done钩子，确保在打包完成后执行
              compiler.hooks.done.tapAsync('BuildDeployPlugin', async (stats, callback) => {
                try {
                  console.log('📦 构建完成，开始执行文件复制...')

                  // 检查构建是否成功
                  if (stats.hasErrors()) {
                    console.error('❌ 构建有错误，跳过文件复制')
                    callback()
                    return
                  }

                  // 执行文件复制操作
                  const buildDeployTools = new BuildDeployTools({
                    maxRetries: 3,
                    retryDelay: 2000,
                  })

                  await buildDeployTools.executeBuildCopy({
                    sourceDir: './dist', // 构建输出目录
                    targetParentDir: 'D:/Work/Vue3/development',
                    autoCommit: true, // 根据需要设置
                    // 🆕 v1.3.0+ 智能提交信息
                    useVcsHistory: true,
                    commitOptions: {
                      prefix: '[Webpack构建]',
                      addTimestamp: true
                    }
                  })

                  console.log('✅ 文件复制完成')
                  callback()
                } catch (error) {
                  console.error('❌ 文件复制失败:', error)
                  callback(error)
                }
              })
            },
          }
        : null,
    ].filter(Boolean), // 过滤掉null值
  },
}

方案2：Vite 集成

在 vite.config.js 中配置：

import { defineConfig } from 'vite'
import { BuildDeployTools } from 'build-deploy-tools'

export default defineConfig({
  // ... 其他配置
  plugins: [
    // ... 其他插件
    {
      name: 'build-deploy',
      closeBundle: async () => {
        if (process.env.NODE_ENV === 'production') {
          console.log('📦 Vite构建完成，开始执行文件复制...')
          
          const buildDeployTools = new BuildDeployTools()
          
          try {
            await buildDeployTools.executeBuildCopy({
              sourceDir: './dist',
              targetParentDir: 'D:/Work/Vue3/development',
              autoCommit: false,
              // 🆕 v1.3.0+ 智能提交信息
              useVcsHistory: true,
              commitOptions: {
                prefix: '[Vite构建]'
              }
            })
            console.log('✅ 文件复制完成')
          } catch (error) {
            console.error('❌ 文件复制失败:', error)
          }
        }
      }
    }
  ]
})

方案3：Rollup 集成

在 rollup.config.js 中配置：

import { BuildDeployTools } from 'build-deploy-tools'

export default {
  // ... 其他配置
  plugins: [
    // ... 其他插件
    {
      name: 'build-deploy',
      writeBundle: async () => {
        if (process.env.NODE_ENV === 'production') {
          console.log('📦 Rollup构建完成，开始执行文件复制...')
          
          const buildDeployTools = new BuildDeployTools()
          
          try {
            await buildDeployTools.executeBuildCopy({
              sourceDir: './dist',
              targetParentDir: 'D:/Work/Vue3/development',
              // 🆕 v1.3.0+ 智能提交信息
              useVcsHistory: true,
              commitOptions: {
                prefix: '[Rollup构建]'
              }
            })
            console.log('✅ 文件复制完成')
          } catch (error) {
            console.error('❌ 文件复制失败:', error)
          }
        }
      }
    }
  ]
}

方案4：npm scripts 后置钩子

利用 npm 的 post 钩子：

{
  "scripts": {
    "build": "vite build",
    "postbuild": "build-copy --auto",
    "build:prod": "vite build",
    "postbuild:prod": "build-copy --auto --commit"
  }
}

方案5：自定义 Node.js 脚本

创建 scripts/build-and-deploy.js：

const { execSync } = require('child_process')
const { BuildDeployTools } = require('build-deploy-tools')

async function buildAndDeploy() {
  try {
    console.log('🚀 开始构建...')
    
    // 执行构建命令
    execSync('npm run build', { stdio: 'inherit' })
    
    console.log('📦 构建完成，开始部署...')
    
    // 执行部署
    const tools = new BuildDeployTools()
    await tools.executeBuildCopy({
      sourceDir: './dist',
      targetParentDir: 'D:/Work/Vue3/development',
      autoCommit: process.env.AUTO_COMMIT === 'true',
      // 🆕 v1.3.0+ 智能提交信息
      useVcsHistory: true,
      commitOptions: {
        prefix: '[自动构建]',
        addTimestamp: true
      }
    })
    
    console.log('🎉 构建和部署完成！')
  } catch (error) {
    console.error('❌ 失败:', error.message)
    process.exit(1)
  }
}

buildAndDeploy()

在 package.json 中添加：

{
  "scripts": {
    "deploy": "node scripts/build-and-deploy.js",
    "deploy:auto": "AUTO_COMMIT=true node scripts/build-and-deploy.js"
  }
}

⚙️ 配置选项

命令行参数

参数	说明	示例
--auto	启用自动模式	build-copy --auto
--commit	强制自动提交到 SVN	build-copy --commit
--no-commit	禁止提交到 SVN	build-copy --no-commit
--no-notification	禁用系统通知	build-copy --no-notification
--build=<name>	指定构建文件名	build-copy --build=myapp
--target=<path>	指定目标目录	build-copy --target=D:/Projects
🆕 --source=<path>	指定源目录	build-copy --source=./dist
🆕 --message=<信息>	自定义提交信息	build-copy --message="修复bug"
🆕 --commit-message=<信息>	自定义提交信息（别名）	build-copy --commit-message="版本发布"
🆕 --no-vcs-history	禁用版本控制历史	build-copy --no-vcs-history
🆕 --add-timestamp	添加时间戳	build-copy --add-timestamp
🆕 --prefix=<前缀>	添加前缀	build-copy --prefix="[部署]"
🆕 --suffix=<后缀>	添加后缀	build-copy --suffix="[完成]"

环境变量

📁 目录和文件配置

变量	说明	示例
TARGET_DIR=<目录>	指定目标目录（优先级高于默认值）	TARGET_DIR=D:/Work/Vue3/myproject build-copy
SOURCE_DIR=<目录>	指定源目录（优先级高于默认值）	SOURCE_DIR=./dist build-copy
BUILD_NAME=<文件名>	指定构建文件名（如果 SOURCE_DIR 未设置，将作为源目录名）	BUILD_NAME=myapp build-copy

注意：如果 SOURCE_DIR 未设置，系统会自动使用 BUILD_NAME 对应的目录作为源目录。 | npm_config_target=<目录> | 指定目标目录（npm配置方式） | npm run build-copy -- --target=D:/Work/Vue3/myproject | | npm_config_source=<目录> | 指定源目录（npm配置方式） | npm run build-copy -- --source=./dist | | npm_config_build=<文件名> | 指定构建文件名（npm配置方式） | npm run build-copy -- --build=myapp |

注意：使用 npm run 时，有两种方式传递参数：

• ✅ 方式1（推荐）：使用双破折号 -- 分隔 npm 参数和脚本参数

  npm run build-copy -- --build=vam4
  

• ✅ 方式2：直接传递参数（npm 会将 --build=vam4 转换为 npm_config_build=vam4 环境变量）

  npm run build-copy --build=vam4
  

  注意：虽然会有警告信息，但功能正常，源目录会正确使用 vam4。

推荐：直接使用全局命令 build-copy --build=vam4 或 npx build-deploy-tools build-copy --build=vam4，无需双破折号，也不会有警告。

🤖 自动化配置

变量	说明	示例
CI=true	CI 环境自动启用自动模式	CI=true build-copy
AUTO_MODE=true	启用自动模式	AUTO_MODE=true build-copy
AUTO_COMMIT=true	启用自动提交	AUTO_COMMIT=true build-copy
npm_config_auto=true	启用自动模式（npm配置方式）	npm run build-copy -- --auto
npm_config_commit_cli=true	启用自动提交（npm配置方式）	npm run build-copy -- --commit
npm_config_notification=false	禁用通知（npm配置方式）	npm run build-copy -- --notification=false
USE_NOTIFICATION=false	禁用通知（环境变量方式）	USE_NOTIFICATION=false build-copy

📝 提交配置

变量	说明	示例
COMMIT_MESSAGE=<信息>	自定义提交信息	COMMIT_MESSAGE="修复登录问题" build-copy
USE_VCS_HISTORY=false	禁用版本控制历史（默认true）	USE_VCS_HISTORY=false build-copy

🔄 重试配置

变量	说明	示例
MAX_RETRIES=<次数>	最大重试次数	MAX_RETRIES=5 build-copy
RETRY_DELAY=<毫秒>	重试延迟时间	RETRY_DELAY=3000 build-copy

📋 优先级说明

环境变量的优先级顺序（从高到低）：

• 命令行参数 ⭐ - --target=, --source=, --build= 等（最高优先级，会覆盖其他配置）
• npm配置 - npm_config_* 环境变量
• 系统环境变量和 .env 文件 - TARGET_DIR, SOURCE_DIR, BUILD_NAME 等
  • 系统环境变量和 .env 文件中的变量优先级相同
  • .env 文件会在模块加载时自动加载到环境变量中
• 默认值 - 代码中定义的默认值

重要：命令行参数会优先于 .env 文件中的配置。如果同时指定了命令行参数和 .env 文件，命令行参数会生效。

📄 使用 .env 文件（推荐）

.env 文件是最方便的配置方式，适合本地开发环境：

# 1. 安装 dotenv（如果还没安装）
npm install dotenv

# 2. 复制示例文件
cp env.example .env

# 3. 编辑 .env 文件，设置你的配置
# TARGET_DIR=D:/Work/Vue3/myproject
# BUILD_NAME=myapp
# AUTO_MODE=true

# 4. 使用（.env 文件会自动加载）
build-copy

注意：dotenv 是可选依赖，如果不安装，.env 文件不会被加载，但你可以使用系统环境变量或命令行参数。

详细使用指南请参考：📖 环境变量使用指南

🧠 智能提交信息功能 (v1.3.0+)

🎯 功能特性

智能提交信息功能能够自动从当前项目的版本控制系统（Git或SVN）获取最近一次提交信息，作为部署时的提交信息，保持代码变更与部署记录的一致性。

🔧 优先级机制

• 自定义信息 - 手动指定的提交信息（最高优先级）
• Git最近提交 - 从当前Git仓库获取最近一次提交信息
• SVN最近提交 - 从当前SVN工作目录获取最近一次提交信息
• 默认信息 - 使用默认的"更新构建文件"

🎨 格式化选项

• 前缀/后缀 - 为提交信息添加自定义前缀或后缀
• 时间戳 - 自动添加当前时间戳
• 组合使用 - 支持多种格式化选项组合

📝 使用示例

# 基本使用 - 自动获取版本控制提交信息
build-copy --auto --commit

# 自定义提交信息
build-copy --message="紧急修复支付问题" --commit

# 格式化选项
build-copy --prefix="🚀[生产]" --add-timestamp --commit
# 结果：🚀[生产] 修复用户登录验证问题 [2024-01-15 14:30]

# 禁用版本控制历史，仅使用默认信息
build-copy --no-vcs-history --commit

💻 编程接口

await tools.executeBuildCopy({
  sourceDir: './dist',
  targetParentDir: 'D:/Work/Vue3/development',
  autoCommit: true,
  // 智能提交信息配置
  useVcsHistory: true,        // 启用版本控制历史
  commitMessage: null,        // 使用智能获取的信息
  commitOptions: {
    prefix: '[自动部署]',
    suffix: '[完成]',
    addTimestamp: true
  }
})

详细使用指南请参考：📖 智能提交信息示例文档

🌍 跨平台支持

本工具支持以下平台：

• ✅ Windows (Windows 10/11)
• ✅ macOS (macOS 10.14+)
• ✅ Linux (Ubuntu, CentOS, 等)

📚 文档

快速导航: 📘 安装指南 | 🚀 快速开始 | 📚 完整文档

详细文档: 通知功能 | 集成示例 | 智能提交信息 | 性能优化 | 环境变量使用

其他: 更新日志 | 配置示例

🛠️ API 文档

BuildDeployTools 类

构造函数

const tools = new BuildDeployTools(options)

选项 (options):

• maxRetries (number): 最大重试次数，默认 3
• retryDelay (number): 重试延迟时间(毫秒)，默认 2000
• defaultFileName (string): 默认文件名，默认 'vam3'

主要方法

executeBuildCopy(config)

执行完整的构建复制流程

参数:

• config.sourceDir (string): 源目录路径
• config.targetParentDir (string): 目标父目录路径
• config.fileName (string, 可选): 构建文件名
• config.autoCommit (boolean, 可选): 是否自动提交到 SVN
• 🆕 config.commitMessage (string, 可选): 自定义提交信息
• 🆕 config.useVcsHistory (boolean, 可选): 是否使用版本控制历史，默认true
• 🆕 config.commitOptions (object, 可选): 提交信息格式化选项
  • prefix (string): 前缀
  • suffix (string): 后缀
  • addTimestamp (boolean): 是否添加时间戳

返回: Promise<boolean>

testNotification()

测试通知功能

返回: Promise<boolean>

🛠️ 故障排除

常见问题

1. 系统通知不显示

解决方案:

# 使用命令行模式
build-copy --no-notification

2. SVN 操作失败

解决方案:

• 确保目标目录是 SVN 工作副本
• 检查 SVN 权限和网络连接

3. 源目录不存在

解决方案:

# 先执行构建
npm run build
# 再执行部署
npm run deploy

🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

• Fork 本仓库
• 创建特性分支 (git checkout -b feature/amazing-feature)
• 提交更改 (git commit -m 'Add some amazing feature')
• 推送到分支 (git push origin feature/amazing-feature)
• 创建 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🔗 相关链接

• 📦 npm 包
• 🐛 问题反馈
• 📝 更新日志

Build Deploy Tools - 让构建部署更简单、更可靠！ 🚀