手写 create-vite：从零到一打造自己的脚手架

mkdir my-create-vite
cd my-create-vite
npm init -y

npm install --save minimist prompts chalk

npm install --save-dev typescript @types/node @types/minimist @types/prompts

npx tsc --init

{
  "compilerOptions": {
    "target": "es2020",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "dist",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "types": ["node"]
  },
  "exclude": ["template-**"]
}

{
  ...
  "type": "module",
  ...
}

// src/index.ts
import minimist from "minimist"

const argv = minimist(process.argv.slice(2))

console.log(argv)

// src/index.ts
import minimist from "minimist"
import chalk from "chalk"

// 定义帮助信息
const helpMessage = `
Usage: create-vite [OPTION]... [DIRECTORY]

Create a new Vite project in JavaScript or TypeScript.
With no arguments, start the CLI in interactive mode.

Options:
  -t, --template NAME        use a specific template

Available templates:
${chalk.yellow("vanilla-ts     vanilla")}
${chalk.green("vue-ts         vue")}
${chalk.cyan("react-ts       react")}
${chalk.cyan("react-swc-ts   react-swc")}
${chalk.magenta("preact-ts      preact")}
${chalk.redBright("lit-ts         lit")}
${chalk.red("svelte-ts      svelte")}
${chalk.blue("solid-ts       solid")}
${chalk.blueBright("qwik-ts        qwik")}
`

async function init() {
  const argv = minimist<{
    template?: string
    help?: boolean
  }>(process.argv.slice(2), {
    alias: { h: "help", t: "template" },
    string: ["_"] // 确保位置参数被解析为字符串
  })

  if (argv.help) {
    console.log(helpMessage)
    return
  }

  // ... 后续逻辑
}

init().catch((e) => {
  console.error(e)
})

// 在 init 函数上方添加
function formatTargetDir(targetDir: string | undefined) {
  return targetDir?.trim().replace(/\/+$/g, "")
}

const defaultTargetDir = "vite-project"

// 在 init 函数内部
async function init() {
  // ... argv 解析之后

  const argTargetDir = formatTargetDir(argv._[0])
  const argTemplate = argv.template || argv.t

  let targetDir = argTargetDir || defaultTargetDir
  console.log(`Scaffolding project in: ${targetDir}`)
}

// src/index.ts
import prompts from "prompts"
// ...

async function init() {
  // ...

  let result: prompts.Answers<"projectName">

  try {
    result = await prompts(
      [
        {
          type: argTargetDir ? null : "text",
          name: "projectName",
          message: chalk.reset("Project name:"),
          initial: defaultTargetDir,
          onState: (state) => {
            targetDir = formatTargetDir(state.value) || defaultTargetDir
          }
        }
      ],
      {
        onCancel: () => {
          throw new Error(chalk.red("✖") + " Operation cancelled")
        }
      }
    )
  } catch (cancelled: any) {
    console.log(cancelled.message)
    return
  }

  const { projectName } = result
  // ...
}

// src/index.ts

type Framework = {
  name: string
  display: string
  color: (str: string | number) => string
  variants: FrameworkVariant[]
}

type FrameworkVariant = {
  name: string
  display: string
  color: (str: string | number) => string
  customCommand?: string
}

// src/index.ts

const FRAMEWORKS: Framework[] = [
  {
    name: "vue",
    display: "Vue",
    color: chalk.green,
    variants: [
      {
        name: "vue-ts",
        display: "TypeScript",
        color: chalk.blue
      },
      {
        name: "vue",
        display: "JavaScript",
        color: chalk.yellow
      }
    ]
  },
  {
    name: "react",
    display: "React",
    color: chalk.cyan,
    variants: [
      {
        name: "react-ts",
        display: "TypeScript",
        color: chalk.blue
      },
      {
        name: "react-swc-ts",
        display: "TypeScript + SWC",
        color: chalk.blue
      },
      {
        name: "react",
        display: "JavaScript",
        color: chalk.yellow
      },
      {
        name: "react-swc",
        display: "JavaScript + SWC",
        color: chalk.yellow
      }
    ]
  }
]

// 从 FRAMEWORKS 派生出所有模板名称
const TEMPLATES = FRAMEWORKS.map(
  (f) => (f.variants && f.variants.map((v) => v.name)) || [f.name]
).reduce((a, b) => a.concat(b), [])

// src/index.ts -> in init() -> inside prompts array

// ... after projectName question
{
    type: argTemplate && TEMPLATES.includes(argTemplate) ? null : 'select',
    name: 'framework',
    message: chalk.reset('Select a framework:'),
    initial: 0,
    choices: FRAMEWORKS.map((framework) => {
        const frameworkColor = framework.color;
        return {
            title: frameworkColor(framework.display || framework.name),
            value: framework,
        };
    }),
},
{
    type: (framework: Framework) =>
        framework && framework.variants ? 'select' : null,
    name: 'variant',
    message: chalk.reset('Select a variant:'),
    choices: (framework: Framework) =>
        framework.variants.map((variant) => {
            const variantColor = variant.color;
            return {
                title: variantColor(variant.display || variant.name),
                value: variant.name,
            };
        }),
},

// src/index.ts
import * as fs from "node:fs"
import * as path from "node:path"

function copy(src: string, dest: string) {
  const stat = fs.statSync(src)
  if (stat.isDirectory()) {
    copyDir(src, dest)
  } else {
    fs.copyFileSync(src, dest)
  }
}

function copyDir(srcDir: string, destDir: string) {
  fs.mkdirSync(destDir, { recursive: true })
  for (const file of fs.readdirSync(srcDir)) {
    const srcFile = path.resolve(srcDir, file)
    const destFile = path.resolve(destDir, file)
    copy(srcFile, destFile)
  }
}

// src/index.ts -> in init()

// ... after prompts
const { framework, variant } = result

const root = path.join(process.cwd(), targetDir)

if (fs.existsSync(root)) {
  // 如果目录已存在，可以添加逻辑提示用户
}

console.log(`\nScaffolding project in ${root}...`)

const template: string = variant || framework?.name || argTemplate

const templateDir = path.resolve(
  fileURLToPath(import.meta.url),
  "../..",
  `template-${template}`
)

const write = (file: string, content?: string) => {
  const targetPath = path.join(root, file)
  if (content) {
    fs.writeFileSync(targetPath, content)
  } else {
    copy(path.join(templateDir, file), targetPath)
  }
}

const files = fs.readdirSync(templateDir)
for (const file of files.filter((f) => f !== "package.json")) {
  write(file)
}

// 单独处理 package.json
const pkg = JSON.parse(
  fs.readFileSync(path.join(templateDir, `package.json`), "utf-8")
)
pkg.name = path.basename(root)
write("package.json", JSON.stringify(pkg, null, 2))

console.log(`\nDone. Now run:\n`)
console.log(`  cd ${targetDir}`)
console.log(`  npm install`)
console.log(`  npm run dev`);

---

## 7. 整合与测试

现在，我们的 `my-create-vite` 工具已经基本完成了。是时候对它进行一次完整的端到端测试了。

### 7.1 编译代码

首先，在 `package.json` 中添加一个 `build` 脚本：

```json
"scripts": {
  "build": "tsc"
}

npm run build
```bash

这会将 `src/index.ts` 编译到 `dist/index.js`。

### 7.2 本地测试

为了方便测试，可以使用 `npm link` 将本地的包链接到全局，这样就可以像真正的 CLI 工具一样使用它了。

**1. 在 `package.json` 中添加 `bin` 字段：**

```json
{
  "name": "my-create-vite",
  "version": "1.0.0",
  "bin": {
    "my-create-vite": "dist/index.js"
  },
  ...
}
```bash

这个字段告诉 npm，当这个包被安装时，需要创建一个名为 `my-create-vite` 的可执行命令，它指向 `dist/index.js`。

**2. 运行 `npm link`:**

```bash
npm link
```bash

现在，你可以在任何目录下运行 `my-create-vite` 命令了。

### 7.3 端到端测试

尝试用自己的工具创建一个新项目：

```bash
my-create-vite my-test-app --template react-ts
```bash

或者进入交互模式：

```bash
my-create-vite
```text


如果一切顺利，项目将被成功创建。进入项目目录，安装依赖并启动开发服务器，验证项目是否能正常运行。

---

## 8. 总结与展望

通过本次实战，从零到一实现了一个功能虽简但五脏俱全的 `create-vite` 脚手架。回顾一下核心技术点：

- **`minimist`** 用于轻量级命令行参数解析。
- **`prompts`** 用于构建优雅的交互式提问界面。
- **`chalk`** 用于美化终端输出。
- **Node.js `fs` 和 `path` 模块** 用于核心的文件系统操作。
- **ES Module in Node.js** 的现代化配置与实践。

未来，你还可以基于当前版本进行功能扩展，例如：

- **支持更多模板**：轻松扩展 `FRAMEWORKS` 配置即可。
- **更智能的 `package.json` 处理**：例如，合并依赖而不是直接覆盖。
- **发布到 npm**：让全世界的开发者都能使用你的工具。

---

## 9. 附录

### 9.1 常见问题解答 (FAQ)

**Q: 为什么选择 `minimist` 而不是 `commander`？**

A: `create-vite` 的参数结构非常简单（只有 `--template` 和一个可选的目录参数），使用 `minimist` 更加轻量、直接。对于更复杂的 CLI，`commander` 提供了更完善的功能（如自动生成帮助信息、子命令等）。

**Q: `import.meta.url` 是什么？**

A: 在 ES Module 中，`__dirname` 和 `__filename` 这类 CommonJS 变量是不可用的。`import.meta.url` 提供了当前模块的 URL，结合 `fileURLToPath` 可以获取当前文件的绝对路径，这对于定位模板文件至关重要。

### 9.2 调试技巧

- 在 `init` 函数的 `catch` 块中打印完整的错误对象 `console.error(e)`，而不是仅仅 `e.message`，可以获得更详细的堆栈信息。
- 在文件操作部分，多使用 `console.log` 打印路径（如 `root`, `templateDir`, `targetPath`），确保路径拼接的正确性。

### 9.3 参考资料

- [Vite 官方仓库](https://github.com/vitejs/vite)
- [prompts - npm](https://www.npmjs.com/package/prompts)
- [minimist - npm](https://www.npmjs.com/package/minimist)