Steve XBuild CLI

构建与发布工具 - 用于模块化构建和产物管理

概述

Steve XBuild CLI 是一个模块化构建工具，支持多任务并行构建、配置验证和版本管理。工具提供了完整的 TypeScript 支持，同时支持 CommonJS 和 ES 模块两种导入方式。

特性

• 支持多任务并行构建
• 配置验证和错误提示
• 版本管理和更新检查
• 同时支持 CommonJS 和 ES 模块
• 完整的 TypeScript 类型定义
• 可扩展的构建器架构
• 性能监控和报告

安装

# 全局安装
npm install -g steve-xbuild-cli

# 或者作为项目依赖安装
npm install --save-dev steve-xbuild-cli

# 或者从源码安装
git clone https://github.com/cptbtptp1001/steve-xbuild-cli.git
cd steve-xbuild-cli
npm install
npm run build
npm link

快速开始

1. 初始化配置

# 创建 TypeScript 配置文件
xbuild init

# 创建 JavaScript 配置文件
xbuild init --javascript

# 强制覆盖现有配置
xbuild init --force

2. 验证配置

# 验证配置文件
xbuild validate

3. 构建模块

# 默认构建
xbuild build

# 指定环境构建
xbuild build --env test

# 并行构建（4个并发）
xbuild build --concurrency 4

# 指定构建器
xbuild build --builder vite

4. 版本信息

# 显示版本信息
xbuild version

# 使用别名
xbuild v

配置文件示例

TypeScript 配置 (xbuild.config.ts)

import { DefineConfig } from 'steve-xbuild-cli';

const config: DefineConfig = {
	appId: 'my-app',
	outDir: 'dist',
	tasks: [
		{
			name: 'core-module',
			description: '核心模块',
			moduleCode: 'CoreModule',
			visibility: 'public',
			targetContainers: ['web', 'mobile'],
			version: '1.0.0',
			commit: 'initial commit',
			buildOptions: {
				entry: 'src/core/index.ts',
				formats: ['es', 'cjs'],
				define: { VERSION: '"1.0.0"' },
				sourcemap: true,
			},
		},
		{
			name: 'ui-module',
			description: 'UI 模块',
			moduleCode: 'UIModule',
			visibility: 'public',
			targetContainers: ['web'],
			version: '1.0.0',
			commit: 'initial commit',
			buildOptions: {
				entry: 'src/ui/index.ts',
				formats: ['es', 'cjs'],
				sourcemap: true,
			},
		},
	],
};

export default config;

JavaScript 配置 (xbuild.config.js)

/** @type {import('steve-xbuild-cli').DefineConfig} */
module.exports = {
	appId: 'my-app',
	outDir: 'dist',
	tasks: [
		{
			name: 'core-module',
			description: '核心模块',
			moduleCode: 'CoreModule',
			visibility: 'public',
			targetContainers: ['web'],
			version: '1.0.0',
			buildOptions: {
				entry: 'src/core/index.js',
				formats: ['es', 'cjs'],
			},
		},
	],
};

模块导入方式

Steve XBuild CLI 同时支持 CommonJS 和 ES 模块两种导入方式，可以根据项目需求选择合适的导入方式：

CommonJS 导入

// 导入整个模块
const xbuild = require('steve-xbuild-cli');

// 导入特定功能
const { getBuilder } = require('steve-xbuild-cli');

ES 模块导入

// 导入整个模块
import xbuild from 'steve-xbuild-cli';

// 导入特定功能
import { getBuilder } from 'steve-xbuild-cli';

命令行选项

build 命令选项

| 选项 | 缩写 | 描述 | 默认值 | 可选值 | | ------------- | ---- | ------------ | ------ | ------------------- | | --env | -e | 构建环境 | prd | dev, test, pre, prd | | --concurrency | -c | 并发构建数量 | 1 | 正整数 | | --builder | -b | 构建器类型 | vite | vite |

init 命令选项

| 选项 | 缩写 | 描述 | 默认值 | | ------------ | ---- | -------------------- | ------ | | --javascript | -j | 使用 JavaScript 配置 | false | | --force | -f | 强制覆盖配置 | false |

项目结构

steve-xbuild-cli/
├── bin/                  # 命令行入口
├── lib/                  # 编译后的 CommonJS 代码
│   └── esm/              # 编译后的 ES 模块代码
├── src/                  # 源代码
│   ├── builders/         # 构建器实现
│   ├── commands/         # 命令实现
│   ├── config/           # 配置处理
│   ├── constants/        # 常量定义
│   ├── request/          # 网络请求
│   └── utils/            # 工具函数
└── types/                # 类型定义

高级用法

自定义构建器

import { BuilderBase } from 'steve-xbuild-cli';

class CustomBuilder extends BuilderBase {
	async build(task, config, options) {
		// 自定义构建逻辑
		console.log(`Building ${task.name} with custom builder`);

		return {
			task,
			success: true,
			artifacts: [],
			duration: 1000,
		};
	}
}

错误处理

import { handleError, withErrorHandling } from 'steve-xbuild-cli';

// 方式1：手动处理错误
try {
	await someOperation();
} catch (error) {
	handleError(error, '操作名称');
}

// 方式2：使用高阶函数
const safeOperation = withErrorHandling(async () => {
	await someOperation();
}, '操作名称');

await safeOperation();

性能监控

import { performance } from 'steve-xbuild-cli';

// 测量同步函数
const result = performance.measure('operation', () => {
	return expensiveOperation();
});

// 测量异步函数
const result = await performance.measureAsync('async-operation', async () => {
	return await expensiveAsyncOperation();
});

// 生成性能报告
performance.saveReport('performance-report.md');

常见问题

1. 配置文件找不到

确保配置文件位于项目根目录，命名为：

• xbuild.config.ts (TypeScript)
• xbuild.config.js (JavaScript)

2. 构建失败

检查：

• 模块入口文件是否存在
• 依赖包是否安装
• 网络连接是否正常

3. 版本冲突

使用 xbuild version 检查本地和线上版本是否一致。

开发指南

添加新命令

1. 在 src/commands/ 目录创建新命令文件
2. 实现 CommandDefinition 接口
3. 在 src/commands/registry.ts 中注册命令

// src/commands/new-command.ts
import { createCommand } from './registry';

async function handler(options: any) {
	// 命令处理逻辑
}

export default createCommand('new-command', '命令描述', handler, {
	options: [{ flags: '-o, --option', description: '选项描述' }],
});

扩展类型定义

在 types/ 目录中添加或修改类型定义文件。

贡献指南

1. Fork 项目
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request

许可证

MIT License