开发脚手架

发表于 分类于 阅读次数：

可执行文件

像 vite，webpack-cli 等手脚架工具，它们可以通过命令行执行一些操作，比如：

1
2
3
4
vite
vite build
webpack server
webpack build

这是一个脚手架最基本的功能，那这是怎么实现的呢？
其实，只需要配置 package.json 的 bin 字段即可。

bin

package.json 文件中的 bin 字段用于定义你的 npm 包中可执行文件的路径。这使得你可以将包发布到 npm 注册表，并允许其他用户通过命令行直接运行这些可执行文件。
bin 字段可以是一个字符串（如果你只有一个可执行文件）或一个对象（如果你有多个可执行文件）。
如果是一个字符串，那这个字符串是可执行文件的路径，此时 name 字段就是命令名称。

1
2
3
4
{
    "name": "test-cli",
    "bin": "index.js"
}

如果是一个对象，那么每个键值对表示命令名和对应的可执行文件路径。

1
2
3
4
5
{
    "bin": {
        "test-cli": "index.js"
    }
}

当我们执行 test-cli（已链接到全局）或 npx test-cli 时，发现是打开了 index.js 文件而不是执行，这是因为可执行文件缺少了 shebang 行，即：

1
#! /usr/bin/env node

Shebang 行告诉操作系统使用 /usr/bin/env node 来执行这个脚本。/usr/bin/env node 是一种跨平台的方式来查找并使用当前环境中的 node 可执行文件。
在 index.js 文件的开头加上 Shebang 行后即可成功执行。

本地调试

当我们想要在本地测试一下自己开发的脚手架时：

1
test-cli

发现终端报错说找不到这个命令，这是因为项目没有被链接到全局。
此时，我们可以在项目根目录下运行

1
npx test-cli

来进行简单调试，若希望在其他项目中调试，就必须将其链接到全局。
我们可以通过 npm link 将其链接到全局。
在项目根目录执行 npm link 后，该项目会被添加到 node 的 node_modules 目录中，之后便可以在任意地方执行 test-cli 命令了。
此外，npm link 还可以让我们在项目中引用本地库。
比如现在有一个项目叫 hello-world，在其目录下执行

1
npm link test-cli

这时，test-cli 就被添加到了 hello-world 的 node_modules 目录中，我们可以在 hello-world 项目中引入并使用 test-cli。

工具库

开发脚手架会用到一些工具库，比如：

  • commander：自定义命令、选项、参数等
  • inquirer：交互式命令行，询问用户并记录结果
  • chalk：美化控制台输出，包括颜色、背景色、下划线等
  • ora：控制台 loading 样式
  • figlet：艺术字
  • easy-table：控制台输出表格
  • cross-spawn：跨平台调用系统命令

下面简单介绍一下这些库的用法。

commander

引入
1
import { program } from "commander";

或者

1
2
3
import { Command } from "commander";

const program = new Command();
为一级命令添加描述
1
2
3
4
5
6
7
import { program } from "commander";

program
    .name("test-cli")
    .version("0.0.1")
    .usage("<command> [options]")
    .description("A CLI tool to generate a new project");

这些信息会在执行 test-cli 时展示出来。

定义二级命令
1
2
3
4
5
6
7
8
9
10
11
12
program
    .command("run")
    .description("Run a project")
    .argument("<projectName>", "project name")
    .option("-p, --port <port>", "Port to run the server on", "3000")
    .option("-h, --host <host>", "Serve to run", "localhost")
    .action((name, options) => {
        console.log(name);
        console.log("Running project", options.port, options.serve);
    });

program.parse();
1
test-cli run hello-world -p 8080 -h 0.0.0.0

当输完命令回车后调用 action 方法，其参数是 argument 和 包含 option 的对象。
program.parse() 方法用于解析命令行参数，必须要执行。

定义三（更多）级命令
1
2
3
4
5
6
7
8
9
10
program
    .command("run")
    .command("webpack")
    .option("-p, --port <port>", "Port to run the server on", "3000")
    .option("-h, --host <host>", "Serve to run", "localhost")
    .action((options) => {
        console.log("Running project", options.port, options.serve);
    });

program.parse();
1
test-cli run webpack --port 8080 --host localhost

inquirer

安装
1
npm i @inquirer/prompts
使用

交互式命令一般在执行完一条指令后执行。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import { input, select, confirm } from "@inquirer/prompts";

program.command("create").action(async () => {
    answers.projectName = await input({
        message: "Input the project name",
        validate: (value) => {
            if (value.trim() === "") {
                return "Project name cannot be empty!";
            }
            return true;
        }
    });
    if (existsSync(resolve(targetDir, projectName || answers.projectName!))) {
        answers.overwrite = await confirm({
            message: "The directory already exists, do you want to overwrite it"
        });
    }
    answers.type = await select({
        message: "Select the language type",
        choices: ["javascript", "typescript"]
    });
});

chalk

引入
1
import chalk from "chalk";

或

1
2
3
import { Chalk } from "chalk";

const customChalk = new Chalk({ level: 2 });
基本用法
1
2
3
4
5
6
7
import chalk from "chalk";

chalk.green("hello world");
chalk.blod("hello world");
chalk.italic("hello world");
chalk.green.bold.italic("hello world");
chalk.bgRed("hello" + chalk.underline("world"));
在项目中的应用
1
2
3
4
5
6
7
8
process.on("uncaughtException", (error) => {
    if (error instanceof Error && error.name === "ExitPromptError") {
        console.log("👋 " + chalk.green("until next time!"));
    } else {
        console.log(chalk.red.bold.italic("An error occurred: " + error.message));
        process.exit(1);
    }
});

ora

基本用法
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import ora from "ora";

const spinner = ora("Creating project...");
// 设置 loading 形状
spinner.spinner = "boxBounce"；
// 设置 loading 颜色
spinner.color = "green";

// 开始
spinner.start();

// 结束
spinner.stop();
spinner.succeed("successfully");
spinner.fail("failed");
spinner.warn("warn");
在项目中的应用
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
program.command("create").action(() => {
    prompt([
        {
            name: "projectName",
            type: "input",
            message: "项目名称"
        }
    ])
        .then(() => {
            const spinner = ora("Creating project...");
            spinner.start();
            copyTemplate()
                .then(() => {
                    spinner.succeed(chalk.green.bold.italic("Project created successfully!"));
                })
                .catch(() => {
                    spinner.fail(chalk.red("Project created failed!"));
                });
        })
        .catch((err) => {
            console.log(chalk.white.bgRed.bold(err.message));
        });
});