bc-depoly

一个功能完善的部署工具库，提供 FTP 上传、版本管理、Git 操作和文件操作功能。使用 TypeScript 编写，提供完整的类型定义。

功能特性

• 📤 FTP 上传 - 支持上传本地目录到 FTP 服务器
• 📦 版本管理 - 自动递增 package.json 版本号
• 🔀 Git 操作 - 自动化 Git 提交、打标签和推送
• 📁 文件操作 - 提供文件和目录的移动、复制、删除功能
• 📝 文件内容操作 - 读取、写入、替换文件内容
• 🔍 文件查找 - 支持按扩展名、模式查找文件
• ⚙️ 命令执行 - 执行 shell 命令
• 📊 文件信息 - 获取文件大小、修改时间等信息
• 🔧 工具函数 - 路径操作、环境变量、目录管理等实用工具
• 🔷 TypeScript - 完整的 TypeScript 支持，内置类型定义

安装

npm install bc-depoly

开发

本项目使用 TypeScript 编写。开发时：

# 安装依赖
npm install

# 构建项目
npm run build

# 运行测试
npm test

# 监听模式运行测试
npm run test:watch

# 生成测试覆盖率报告
npm run test:coverage

# 开发模式（使用 tsx）
npm run dev

测试

项目使用 Vitest 作为测试框架，包含完整的单元测试：

• 文件操作测试 - 测试文件/目录的复制、移动、删除等操作
• 文件内容操作测试 - 测试文件读写、内容替换等功能
• 工具函数测试 - 测试路径操作、环境变量等工具函数
• 版本管理测试 - 测试版本号的获取和更新
• 命令执行测试 - 测试 shell 命令执行功能

所有测试都通过 ✅

使用方法

FTP 上传

import { uploadToFTP } from 'bc-depoly';

await uploadToFTP(
  {
    host: 'ftp.example.com',
    user: 'username',
    password: 'password',
    port: 21
  },
  './dist',           // 本地目录
  '/public_html'      // 远程目录
);

版本管理

import { updateVersion, getCurrentVersion } from 'bc-depoly';

// 获取当前版本
const currentVersion = getCurrentVersion();
console.log(currentVersion); // "1.0.11"

// 更新版本（补丁版本 +1）
const newVersion = updateVersion();
console.log(newVersion); // "1.0.12"

Git 操作

import { gitCommit } from 'bc-depoly';

// 提交代码并打标签
await gitCommit({
  branch: 'main',
  message: 'feat: 添加新功能',
  skipTag: false,
  skipPush: false
});

// 仅提交，不打标签
await gitCommit({
  message: 'fix: 修复bug',
  skipTag: true
});

文件操作

import { moveFiles, copyDirectory, deletePath } from 'bc-depoly';

// 移动文件/目录
moveFiles('./src', './dist');

// 复制目录
copyDirectory('./src', './backup', {
  overwrite: true  // 覆盖已存在的文件
});

// 删除文件或目录
deletePath('./old-file.txt');
deletePath('./old-dir', { force: true }); // 如果不存在也不报错

文件内容操作

import { readFile, writeFile, replaceFileContent } from 'bc-depoly';

// 读取文件
const config = readFile('./config.json');
const json = JSON.parse(config);

// 写入文件
writeFile('./output.txt', 'Hello World');

// 替换文件内容
replaceFileContent('./config.js', 'localhost', 'production.example.com');
replaceFileContent('./package.json', /"version":\s*"[^"]+"/, '"version": "2.0.0"');

文件查找

import { findFiles } from 'bc-depoly';

// 查找所有 TypeScript 文件
const tsFiles = findFiles('./src', {
  extensions: ['.ts', '.tsx'],
  excludeDirs: ['node_modules', 'dist']
});

// 查找测试文件
const testFiles = findFiles('./src', {
  pattern: '*.test.ts',
  recursive: true
});

文件信息

import { getFileInfo, getDirectorySize } from 'bc-depoly';

// 获取文件信息
const info = getFileInfo('./package.json');
console.log(`File size: ${info.size} bytes`);
console.log(`Modified: ${info.mtime}`);

// 获取目录大小
const size = getDirectorySize('./dist');
console.log(`Directory size: ${(size / 1024 / 1024).toFixed(2)} MB`);

命令执行

import { executeCommand } from 'bc-depoly';

// 执行命令并获取输出
const version = executeCommand('npm --version');
console.log(`npm version: ${version}`);

// 执行命令并显示实时输出
executeCommand('npm install', { stdio: 'inherit' });

// 执行命令，失败时不抛出错误
executeCommand('npm run test', { throwOnError: false });

工具函数

import {
  fileExists,
  ensureDirectory,
  getEnv,
  normalizePath,
  getFileExtension,
  joinPaths
} from 'bc-depoly';

// 检查文件是否存在
if (fileExists('./config.json')) {
  // 处理文件
}

// 确保目录存在
ensureDirectory('./dist/assets');

// 获取环境变量
const apiUrl = getEnv('API_URL', 'http://localhost:3000');
const port = parseInt(getEnv('PORT', '3000'));

// 规范化路径
const absPath = normalizePath('./src/../dist/index.js');

// 获取文件扩展名
const ext = getFileExtension('./index.ts'); // '.ts'

// 合并路径
const fullPath = joinPaths('./src', 'utils', 'helper.ts');

API 文档

uploadToFTP(config, localPath, remotePath)

上传本地目录到 FTP 服务器。

参数：

• config (AccessOptions): FTP 客户端配置选项（来自 basic-ftp 库）
• localPath (string): 本地目录路径
• remotePath (string): 远程目录路径

返回： Promise<void>

抛出： 当本地路径不存在或上传失败时抛出错误

updateVersion(packagePath?)

自动递增 package.json 的版本号（补丁版本）。

参数：

• packagePath (string, 可选): package.json 文件路径，默认为当前工作目录下的 package.json

返回： string - 更新后的版本号

抛出： 当 package.json 不存在或版本格式错误时抛出错误

getCurrentVersion(packagePath?)

获取当前 package.json 中的版本号。

参数：

• packagePath (string, 可选): package.json 文件路径，默认为当前工作目录下的 package.json

返回： string - 当前版本号

抛出： 当 package.json 不存在或版本字段缺失时抛出错误

gitCommit(options?)

执行 Git 提交、打标签及推送。

参数：

• options (GitCommitOptions, 可选):
  • branch (string): 目标分支名，默认为 'main'
  • message (string): 提交信息前缀，默认为 '其它: '
  • skipTag (boolean): 是否跳过打标签，默认为 false
  • skipPush (boolean): 是否跳过推送，默认为 false
  • onError (Function): 自定义错误处理器

返回： Promise<void>

抛出： 当 Git 操作失败时抛出错误

moveFiles(sourceDir, targetDir)

移动文件或目录从源路径到目标路径（递归处理）。

参数：

• sourceDir (string): 源目录路径
• targetDir (string): 目标目录路径

抛出： 当源目录不存在时抛出错误

copyDirectory(sourceDir, targetDir, options?)

递归复制目录及其内容到目标路径。

参数：

• sourceDir (string): 源目录路径
• targetDir (string): 目标目录路径
• options (CopyDirectoryOptions, 可选):
  • overwrite (boolean): 是否覆盖已存在的文件，默认为 true

抛出： 当源目录不存在时抛出错误

deletePath(targetPath, options?)

删除文件或目录（递归删除）。

参数：

• targetPath (string): 要删除的文件或目录路径
• options (object, 可选):
  • force (boolean): 如果路径不存在也不报错，默认为 false

抛出： 当路径不存在且 force 为 false 时抛出错误

readFile(filePath, encoding?)

读取文件内容。

参数：

• filePath (string): 文件路径
• encoding (BufferEncoding, 可选): 文件编码，默认为 'utf8'

返回： string - 文件内容

抛出： 当文件不存在时抛出错误

writeFile(filePath, content, encoding?, createDir?)

写入文件内容。

参数：

• filePath (string): 文件路径
• content (string): 文件内容
• encoding (BufferEncoding, 可选): 文件编码，默认为 'utf8'
• createDir (boolean, 可选): 是否自动创建目录，默认为 true

抛出： 当写入失败时抛出错误

replaceFileContent(filePath, searchValue, replaceValue, encoding?)

替换文件内容。

参数：

• filePath (string): 文件路径
• searchValue (string | RegExp): 要替换的内容（字符串或正则表达式）
• replaceValue (string): 替换后的内容
• encoding (BufferEncoding, 可选): 文件编码，默认为 'utf8'

返回： boolean - 是否进行了替换

抛出： 当文件不存在或替换失败时抛出错误

executeCommand(command, options?)

执行 shell 命令。

参数：

• command (string): 要执行的命令
• options (ExecuteCommandOptions, 可选):
  • throwOnError (boolean): 是否在失败时抛出错误，默认为 true
  • 其他 Node.js execSync 选项

返回： string - 命令输出结果

抛出： 当命令执行失败且 throwOnError 为 true 时抛出错误

findFiles(dir, options?)

查找文件。

参数：

• dir (string): 要搜索的目录
• options (FindFilesOptions, 可选):
  • recursive (boolean): 是否递归查找子目录，默认为 true
  • extensions (string[]): 文件扩展名过滤，例如 ['.js', '.ts']
  • pattern (string): 文件名模式匹配（支持 glob），例如 '*.test.js'
  • excludeDirs (string[]): 排除的目录名列表

返回： string[] - 找到的文件路径数组

getFileInfo(filePath)

获取文件信息。

参数：

• filePath (string): 文件或目录路径

返回： FileInfo - 文件信息对象

抛出： 当路径不存在时抛出错误

getDirectorySize(dirPath)

获取目录大小（递归计算所有文件的总大小）。

参数：

• dirPath (string): 目录路径

返回： number - 目录总大小（字节）

抛出： 当目录不存在时抛出错误

fileExists(filePath)

检查文件或目录是否存在。

参数：

• filePath (string): 文件或目录路径

返回： boolean - 如果存在返回 true，否则返回 false

ensureDirectory(dirPath, recursive?)

确保目录存在（如果不存在则创建）。

参数：

• dirPath (string): 目录路径
• recursive (boolean, 可选): 是否递归创建父目录，默认为 true

getEnv(key, defaultValue?)

获取环境变量，如果不存在则返回默认值。

参数：

• key (string): 环境变量名
• defaultValue (string, 可选): 默认值，默认为 ''

返回： string - 环境变量值或默认值

normalizePath(filePath)

规范化路径（解决相对路径、.. 等）。

参数：

• filePath (string): 文件路径

返回： string - 规范化后的绝对路径

getFileExtension(filePath)

获取文件扩展名。

参数：

• filePath (string): 文件路径

返回： string - 文件扩展名（包含点号），如果没有扩展名返回空字符串

getFileNameWithoutExt(filePath)

获取文件名（不含扩展名）。

参数：

• filePath (string): 文件路径

返回： string - 文件名（不含扩展名）

joinPaths(...paths)

合并路径。

参数：

• paths (string[]): 路径片段数组

返回： string - 合并后的路径

TypeScript 支持

本项目使用 TypeScript 编写，提供完整的类型定义。所有接口都已导出，可以直接使用：

import { 
  uploadToFTP, 
  GitCommitOptions, 
  CopyDirectoryOptions,
  FindFilesOptions,
  ExecuteCommandOptions,
  FileInfo
} from 'bc-depoly';

const gitOptions: GitCommitOptions = {
  branch: 'main',
  message: 'feat: 新功能',
  skipTag: false
};

await gitCommit(gitOptions);

const copyOptions: CopyDirectoryOptions = {
  overwrite: true
};

copyDirectory('./src', './dist', copyOptions);

完整示例

import { 
  updateVersion, 
  getCurrentVersion, 
  gitCommit, 
  uploadToFTP,
  copyDirectory 
} from 'bc-depoly';

async function deploy(): Promise<void> {
  try {
    // 1. 复制构建文件
    copyDirectory('./build', './dist');

    // 2. 更新版本
    updateVersion();
    const version = getCurrentVersion();
    console.log(`Building version ${version}`);

    // 3. 提交到 Git
    await gitCommit({
      message: `chore: 发布版本 ${version}`,
      skipTag: false
    });

    // 4. 上传到 FTP
    await uploadToFTP(
      {
        host: process.env.FTP_HOST!,
        user: process.env.FTP_USER!,
        password: process.env.FTP_PASSWORD!
      },
      './dist',
      '/public_html'
    );

    console.log('部署完成！');
  } catch (error) {
    console.error('部署失败:', error);
    process.exit(1);
  }
}

deploy();

项目结构

bc-depoly/
├── src/                  # TypeScript 源代码
│   ├── index.ts          # 主入口文件（统一导出）
│   ├── types.ts          # 类型定义
│   ├── constants.ts      # 常量定义
│   ├── ftp.ts            # FTP 上传功能
│   ├── git.ts            # Git 操作功能
│   ├── version.ts        # 版本管理功能
│   ├── file-operations.ts # 文件操作功能
│   ├── path-utils.ts     # 路径工具函数
│   ├── env-utils.ts      # 环境变量工具
│   ├── command.ts        # 命令执行功能
│   └── utils.ts          # 通用工具函数
├── tests/                # 测试文件目录
│   ├── utils.test.ts     # 工具函数测试
│   ├── file-operations.test.ts  # 文件操作测试
│   ├── command.test.ts   # 命令执行测试
│   └── version.test.ts   # 版本管理测试
├── dist/                 # 编译后的 JavaScript 文件（构建后生成）
├── tsconfig.json         # TypeScript 配置文件
├── vitest.config.ts      # Vitest 测试配置
├── package.json          # 项目配置
└── README.md             # 说明文档

要求

• Node.js >= 14.0.0

许可证

ISC