Pilot CLI

🚀 现代化的 TypeScript CLI 工具，用于前端开发环境管理。支持交互式环境选择和灵活的配置定制，兼容任何构建工具（Vite、Webpack、Rollup 等）。

✨ 特性

• 🎯 交互式环境选择 - 通过友好的命令行界面选择开发环境
• ⚡ 快速启动 - 一键启动不同环境的开发服务器
• 🔧 灵活配置 - 支持自定义环境和命令配置
• 🛠️ 构建工具无关 - 兼容 Vite、Webpack、Rollup、Parcel 等任何构建工具
• 📦 零配置使用 - 开箱即用，内置常用环境配置
• 🎨 TypeScript 支持 - 完整的 TypeScript 类型支持
• 🧩 自定义命令 - 支持定义项目特定的命令

• 🚀 快速上手
• 📦 安装
• ⚙️ 自定义配置
  • 使用 init 命令
  • 手动创建配置文件
• 🪝 高级功能
  • Hooks 系统
  • 全局与局部选择器
  • 模板变量
  • 环境变量覆盖
  • 自定义环境变量
  • 自定义命令
• 📝 配置示例
• 🔧 故障排除
• 📄 许可证

🚀 快速上手

1. 安装

在您的项目中通过 pnpm 安装 Pilot CLI：

pnpm add -D @seakoi/pilot-cli

(也支持 npm 和 yarn, 详见 安装 章节)

2. 运行

执行 start 命令 (或直接运行 pilot-cli)：

npx pilot-cli start

您将看到一个交互式菜单，让您选择要启动的环境。

? 请选择环境: (Use arrow keys)
❯ development - 开发环境
  test - 测试环境
  hotfix - 热修复环境
  production - 生产环境

就是这么简单！Pilot CLI 会使用内置的 Vite 配置为您启动开发服务器。

📦 安装

全局安装

npm install -g @seakoi/pilot-cli

项目内安装

# pnpm
pnpm add -D @seakoi/pilot-cli

# npm
npm install --save-dev @seakoi/pilot-cli

# yarn
yarn add -D @seakoi/pilot-cli

⚙️ 自定义配置

想定义自己的环境？有两种方式可以创建配置文件：使用 init 命令或手动创建。

使用 init 命令

最简单的方式是使用内置的 init 命令，它会引导您创建一个配置文件：

npx pilot-cli init

您可以回答一系列问题来定制配置文件，或者使用预设模板：

# 使用 Vite 预设模板
npx pilot-cli init --template=vite

# 使用 Webpack 预设模板
npx pilot-cli init --template=webpack

# 使用 Next.js 预设模板
npx pilot-cli init --template=nextjs

# 强制覆盖现有配置文件
npx pilot-cli init --force

手动创建配置文件

您也可以在项目根目录手动创建 pilot.config.ts 文件：

基础配置

// pilot.config.ts
import type { Config } from "@seakoi/pilot-cli";

export default {
  environments: [
    {
      name: "development",
      value: "development",
      description: "开发环境",
      commands: { // 为 start 和 build 子命令分别配置
        start: {
          cmd: "npx",
          args: ["vite", "--mode", "{{environment.value}}", "--host"],
          env: { // 自定义环境变量
            PORT: "3000",
            API_BASE_URL: "http://localhost:3001",
            DEBUG: "true",
          },
        },
      },
    },
    {
      name: "production",
      value: "production",
      description: "生产环境",
      commands: {
        build: {
          cmd: "npx",
          args: ["vite", "build", "--mode", "{{environment.value}}"],
          env: { // 构建时的环境变量
            NODE_ENV: "{{environment.value}}",
            GENERATE_SOURCEMAP: "false",
          },
        },
      },
    },
  ],
} satisfies Partial<Config>;

使用 defaultCommands 简化配置

如果多个环境使用相似的命令，可以使用 defaultCommands 来避免重复：

// pilot.config.ts
import type { Config } from "@seakoi/pilot-cli";

export default {
  // 为 start 和 build 定义默认命令
  defaultCommands: {
    start: {
      cmd: "npx",
      args: ["vite", "--mode", "{{environment.value}}", "--host"],
      env: { // 自定义环境变量，支持模板变量
        PORT: "3000",
        API_BASE_URL: "https://api.{{environment.name}}.example.com",
        DEBUG: "{{environment.value}}",
      },
    },
    build: {
      cmd: "npx",
      args: ["vite", "build", "--mode", "{{environment.value}}"],
      env: { // 构建时的环境变量
        NODE_ENV: "{{environment.value}}",
        GENERATE_SOURCEMAP: "false",
      },
    },
  },

  environments: [
    {
      name: "development",
      value: "development",
      description: "开发环境",
      // 无需定义 commands，将自动使用 defaultCommands
    },
    {
      name: "production",
      value: "production",
      description: "生产环境",
      // 此处也使用 defaultCommands
    },
  ],
} satisfies Partial<Config>;

配置文件查找顺序

工具会按以下顺序查找并加载配置文件：

1. pilot.config.ts
2. pilot.config.js
3. pilot.config.mjs

如果没有找到，则使用内置的默认配置。

🪝 高级功能

Hooks 系统

Pilot CLI 支持在命令执行前后运行自定义脚本或函数。

• Hook 类型: command (执行 shell 命令) 或 function (执行 JS 函数)。
• Hook 级别: global (在所有环境中执行) 或 environment (在特定环境中执行)。

// pilot.config.ts
import type { Config } from "@seakoi/pilot-cli";

export default {
  // 全局 pre-hooks：在所有环境启动前执行
  globalPreHooks: [
    {
      name: "install-deps",
      type: "command",
      cmd: "npm",
      args: ["install"],
      env: { // Hook 也可以定义自定义环境变量
        CI: "true",
        NPM_CONFIG_REGISTRY: "https://registry.npmmirror.com",
      },
    },
  ],

  // 全局 post-hooks：在所有环境启动后执行
  globalPostHooks: [
    {
      name: "notify",
      type: "function",
      fn: async (environment) => {
        console.log(`🎉 ${environment.name} 环境已启动！`);
      },
    },
  ],

  environments: [
    {
      name: "development",
      value: "development",
      description: "开发环境",
      // 开发环境特定的 pre-hook
      preHooks: [
        {
          name: "clear-cache",
          type: "command",
          cmd: "rm",
          args: ["-rf", "node_modules/.cache"],
        },
      ],
    },
  ],
} satisfies Partial<Config>;

全局与局部选择器

选择器允许在执行命令前进行交互式选择，并将结果注入命令。

• 全局选择器: 在选择环境之前执行。
• 局部选择器: 在选择环境之后、执行命令之前执行。

// pilot.config.ts
export default {
  // 全局选择器：选择平台
  globalSelector: {
    name: "platform",
    type: "selector",
    description: "选择目标平台",
    options: [
      { label: "安卓开发", value: "android" },
      { label: "iOS开发", value: "ios" },
    ],
  },

  environments: [
    {
      name: "development",
      value: "development",
      description: "开发环境",
      // 局部选择器：选择构建类型
      localSelector: {
        name: "buildType",
        type: "selector",
        description: "选择构建类型",
        options: [
          { label: "Debug构建", value: "debug" },
          { label: "Release构建", value: "release" },
        ],
      },
      commands: {
        start: {
          cmd: "npx",
          args: [
            "react-native",
            "run-{{platform}}", // 使用全局选择器结果
            "--variant={{buildType}}" // 使用局部选择器结果
          ]
        },
      },
    },
  ],
};

指定选择器值

您可以通过以下两种方式指定选择器的值，而不是使用交互式选择：

1. 命令行参数：

   # 直接使用选择器名称作为参数
   pilot-cli start --platform=android --buildType=debug
   
   # 指定多个选择器
   pilot-cli build --platform=ios --buildType=release

2. 环境变量：

   # 使用环境变量指定选择器值
   export PILOT_SELECTOR_PLATFORM=android
   export PILOT_SELECTOR_BUILDTYPE=debug
   pilot-cli start

优先级顺序：环境变量 > 命令行参数 > 交互式选择

模板变量

在 args、cmd、env 以及 hooks 中，您可以使用以下模板变量：

• {{environment.value}} - 环境值
• {{environment.name}} - 环境名称
• {{environment.description}} - 环境描述
• {{选择器名称}} - 全局或局部选择器的选择结果值

环境变量覆盖

Pilot CLI 支持通过环境变量覆盖环境选择和模板变量，提供更大的灵活性：

1. 环境选择

您可以使用 PILOT_ENV_VALUE 环境变量直接指定要使用的环境，避免交互式选择：

# 直接使用 staging 环境，不会弹出交互式选择器
export PILOT_ENV_VALUE="staging"
pilot-cli start

2. 模板变量覆盖

您可以使用以下环境变量覆盖模板变量：

# 覆盖环境值（同时也用于环境选择）
export PILOT_ENV_VALUE="staging"

# 覆盖环境名称
export PILOT_ENV_NAME="stage"

# 覆盖环境描述
export PILOT_ENV_DESCRIPTION="预发布环境"

# 覆盖选择器值（例如 platform 选择器）
export PILOT_SELECTOR_PLATFORM="desktop"

3. 选择器值

您可以使用 PILOT_SELECTOR_XXX 环境变量直接指定选择器的值，避免交互式选择：

# 直接使用 web 作为 platform 选择器的值，不会弹出交互式选择器
export PILOT_SELECTOR_PLATFORM="web"
pilot-cli start

优先级顺序：环境变量 > 命令行参数 > 交互式选择

这些环境变量使您能够完全自动化运行命令，无需任何交互，特别适合在 CI/CD 环境中使用。

自定义环境变量

您可以在 commands 和 hooks 中定义自定义环境变量，这些变量会在命令执行时自动设置：

// pilot.config.ts
export default {
  defaultCommands: {
    start: {
      cmd: "npx",
      args: ["vite", "--mode", "{{environment.value}}"],
      env: { // 自定义环境变量
        PORT: "3000", // 固定值
        API_BASE_URL: "https://api.{{environment.name}}.example.com", // 使用模板变量
        DEBUG: "{{environment.value}}", // 根据环境动态设置
      },
    },
    build: {
      cmd: "npx",
      args: ["vite", "build"],
      env: {
        NODE_ENV: "{{environment.value}}",
        GENERATE_SOURCEMAP: "false",
      },
    },
  },
  environments: [
    { name: "development", value: "development", description: "开发环境" },
  ],
};

环境变量优先级：

1. 自定义环境变量（env 字段中的变量）
2. 系统默认环境变量（NODE_ENV 等）
3. 系统环境变量（process.env 中的变量）

自定义环境变量会覆盖系统环境变量，允许您完全控制命令的执行环境。

自定义命令

您可以在配置文件中定义自定义命令，这些命令可以直接通过 pilot-cli <命令名> 执行，无需环境选择：

// pilot.config.ts
export default {
  // 自定义命令配置
  customCommands: {
    // 定义一个 lint 命令
    lint: {
      cmd: 'npm',
      args: ['run', 'lint'],
      env: { NODE_ENV: 'development' },
    },
    // 定义一个 test 命令
    test: {
      cmd: 'npm',
      args: ['run', 'test'],
      env: { NODE_ENV: 'test' },
    },
    // 定义一个 deploy 命令
    deploy: {
      cmd: 'npm',
      args: ['run', 'deploy'],
      env: { CI: 'true' },
    },
  },

  // 其他配置...
};

使用自定义命令：

# 执行 lint 命令
npx pilot-cli lint

# 执行 test 命令
npx pilot-cli test

# 执行 deploy 命令
npx pilot-cli deploy

# 显示详细输出
npx pilot-cli lint --verbose

注意事项：

• 自定义命令不会触发环境选择流程，它们会直接执行
• 自定义命令不能与内置命令 (start, build, init, list) 同名
• 自定义命令支持 --verbose 选项，用于显示详细输出
• 自定义命令支持自定义环境变量 (env 字段)

📝 配置示例

Vite 项目

// pilot.config.ts
export default {
  defaultCommands: {
    start: {
      cmd: "npx",
      args: ["vite", "--mode", "{{environment.value}}", "--host"],
      env: { // 自定义环境变量
        PORT: "3000",
        VITE_API_BASE_URL: "https://api.{{environment.name}}.example.com",
      },
    },
    build: {
      cmd: "npx",
      args: ["vite", "build", "--mode", "{{environment.value}}"],
      env: { // 构建时的环境变量
        NODE_ENV: "{{environment.value}}",
        VITE_APP_ENV: "{{environment.value}}",
      },
    },
  },
  environments: [
    { name: "development", value: "development", description: "开发环境" },
    { name: "production", value: "production", description: "生产环境" },
  ],
};

Webpack 项目

// pilot.config.ts
export default {
  environments: [
    {
      name: "development",
      value: "development",
      description: "开发环境",
      commands: {
        start: {
          cmd: "npx",
          args: ["webpack", "serve", "--mode", "{{environment.value}}"],
          env: {
            PORT: "3000",
            WEBPACK_DEV_SERVER: "true",
          },
        },
      },
    },
    {
      name: "build",
      value: "production",
      description: "构建生产版本",
      commands: {
        build: {
          cmd: "npx",
          args: ["webpack", "--mode", "{{environment.value}}"],
          env: {
            NODE_ENV: "{{environment.value}}",
            GENERATE_SOURCEMAP: "false",
          },
        },
      },
    },
  ],
};

Next.js 项目

// pilot.config.ts
export default {
  environments: [
    {
      name: "development",
      value: "development",
      description: "开发环境",
      commands: { start: { cmd: "npm", args: ["run", "dev"] } },
    },
    {
      name: "build",
      value: "production",
      description: "构建项目",
      commands: { build: { cmd: "npm", args: ["run", "build"] } },
    },
    {
      name: "start",
      value: "production",
      description: "启动生产服务器",
      commands: { start: { cmd: "npm", args: ["run", "start"] } },
    },
  ],
};

🔧 故障排除

常见问题

Q: 提示 "不支持的环境" 错误？ A: 检查你输入的环境名称是否在配置文件的 environments 数组中。

Q: 配置文件不生效？ A: 确保配置文件名称正确（pilot.config.ts 等），并且文件位于项目根目录。

Q: 命令执行失败？ A: 检查 commands 配置是否正确，确保相关依赖已安装。可以尝试添加 --verbose 标志来查看详细输出。

查看帮助信息

# 查看版本
npx pilot-cli --version

# 查看全局帮助
npx pilot-cli --help

# 查看子命令帮助
npx pilot-cli start --help
npx pilot-cli build --help
npx pilot-cli init --help
npx pilot-cli list --help

📄 许可证

ISC