1. 项目概述：为什么你需要 oh-my-codex？

如果你是一名开发者，尤其是经常与命令行（CLI）工具打交道的 Node.js 或 TypeScript 开发者，那么你肯定对“脚手架”这个概念不陌生。从create-react-app到vue-cli，这些工具极大地简化了项目初始化流程。但当你需要为自己或团队创建一套定制化的、可复用的项目模板时，你可能会发现，现有的通用工具要么不够灵活，要么配置起来异常繁琐。这时，一个专注于快速生成和定制 CLI 工具的框架就显得尤为重要。oh-my-codex正是为此而生。

简单来说，oh-my-codex是一个基于 Node.js 和 TypeScript 的 CLI 工具开发框架。它的核心目标不是让你去使用某个现成的 CLI，而是让你能像搭积木一样，快速构建出属于你自己的、功能强大的命令行工具。你可以把它理解为一个“CLI 的 CLI”——一个用来生成 CLI 工具的工具。无论是想为你的开源项目创建一个酷炫的安装引导程序，还是为团队内部开发流程统一项目脚手架，oh-my-codex都能提供一套结构清晰、类型安全、且高度可扩展的解决方案。

我最初接触它，是因为厌倦了每次启动新微服务时都要手动复制粘贴一堆配置文件、修改包名和作者信息。用oh-my-codex写了一个内部模板生成器后，现在团队新成员只需要一行命令，就能得到一个包含完整 TypeScript 配置、ESLint、Prettier、Dockerfile 以及基础 CI/CD 配置的标准化项目骨架，效率提升立竿见影。接下来，我将带你从零开始，彻底掌握这个能让你“造轮子”效率翻倍的神器。

2. 核心设计哲学与架构拆解

2.1 不是另一个“脚手架生成器”

首先要澄清一个常见的误解。很多人看到“Codex”和“CLI”，会下意识地把它归类为像yeoman或plop那样的项目模板生成器。虽然它们有相似之处，但oh-my-codex的定位更底层、更偏向“框架”。yeoman是一个强大的生成器运行环境，你需要为它编写复杂的Generator类；plop则更轻量，专注于基于模板的文件操作。而oh-my-codex的野心是为你提供一套构建完整 CLI 应用的最佳实践和基础设施。

它的设计哲学可以概括为三点：约定优于配置、类型安全至上、插件化扩展。框架本身通过 TypeScript 实现了严格的类型约束，这意味着你在开发 CLI 工具时，命令参数、选项、交互提示等都有完善的类型提示，能极大减少运行时错误。同时，它采用了一种类似“项目模板”的目录结构约定，你的 CLI 逻辑、模板文件、配置都放在预设的位置，框架会自动识别和处理，省去了大量胶水代码。

2.2 核心架构：命令、模板与渲染引擎

要理解oh-my-codex，你需要先了解它的三个核心概念：命令（Command）、模板（Template）和渲染引擎（Renderer）。

命令是你 CLI 工具的入口点。比如你构建了一个叫my-cli的工具，那么my-cli init <project-name>就是一个命令。在oh-my-codex中，命令被定义在src/commands目录下，每个命令都是一个独立的类，继承自框架提供的基类。这个类里定义了命令的名称、描述、参数、选项，以及最关键的run方法——命令执行时的核心逻辑。

模板是你想要生成的项目或文件的蓝图。它们不是简单的文件拷贝，而是包含占位符（例如{{projectName}}、{{author}}）的模板文件。这些模板文件按照一定的目录结构组织在templates文件夹下。oh-my-codex支持使用多种模板引擎，默认是 EJS ，但你也可以轻松切换到 Handlebars 或 Nunjucks。

渲染引擎是连接命令和模板的桥梁。当用户执行一个生成命令时，命令的run方法会调用渲染引擎。引擎会读取对应的模板目录，根据用户输入（或预设的答案）替换掉模板中的所有占位符，然后将处理后的文件输出到目标目录。这个过程是高度可配置的，你可以控制哪些文件被渲染、哪些被忽略、文件权限如何设置等。

这种架构带来的最大好处是关注点分离。你只需要关心：1. 定义用户交互（命令参数和提示）；2. 编写模板文件；3. 将两者通过渲染逻辑绑定。框架负责处理复杂的命令行解析、用户交互、文件系统操作和错误处理，让你能专注于业务逻辑本身。

3. 环境准备与项目初始化实战

3.1 Node.js 与包管理器的选择与避坑

oh-my-codex基于 Node.js，所以第一步是确保你的开发环境正确。从网络热词中可以看到大量关于 Node.js 安装失败的问题，如error installing 24.19.0: node.js v24.19.0 is not yet released或node.js v24.16.0 error: no such module: http_parser。这些问题通常源于版本管理混乱或系统环境异常。

我的强烈建议是使用 Node.js 版本管理工具，如nvm(macOS/Linux) 或nvm-windows。这能让你在不同项目间无缝切换 Node.js 版本，避免全局污染。oh-my-codex对 Node.js 版本要求相对宽松，通常支持当前的 LTS（长期支持版）和最新的 Current 版本。你可以通过nvm install --lts安装最新的 LTS 版本（如 20.x），然后用nvm use <version>切换。

注意：如果你在 Windows 上使用nvm-windows，请务必以管理员身份运行 PowerShell 或 CMD 进行安装和切换操作，否则可能会因权限问题导致失败。安装后，关闭所有终端窗口重新打开，让环境变量生效。

验证安装是否成功：

node --version # 应显示如 v20.11.0 npm --version # 或 yarn --version / pnpm --version

包管理器方面，npm是默认选择，但yarn或pnpm在依赖安装速度和磁盘空间利用上更有优势。oh-my-codex项目本身对这些包管理器都兼容。我个人偏好pnpm，因为它严格的依赖管理能有效避免“幽灵依赖”问题，对于构建需要发布到 npm 的 CLI 工具来说更干净。

3.2 创建你的第一个 Codex CLI 项目

环境就绪后，我们就可以开始创建第一个oh-my-codex项目了。框架提供了一个官方初始化命令，能快速搭建项目骨架。

打开终端，在你喜欢的工作目录下，执行以下命令：

# 使用 npx 直接运行 create-oh-my-codex 包，无需全局安装 npx create-oh-my-codex my-first-codex-cli

这个命令会做几件事：

1. 从 npm 下载create-oh-my-codex这个脚手架工具。
2. 运行它，并在当前目录下创建一个名为my-first-codex-cli的新文件夹。
3. 交互式地询问你一些项目基本信息，如项目名称、描述、作者等。
4. 根据你的回答，生成一个包含oh-my-codex所有基础配置的项目。

如果网络较慢或npx执行有问题，你也可以选择传统方式：

# 1. 创建项目目录并进入 mkdir my-first-codex-cli && cd my-first-codex-cli # 2. 初始化 npm 项目（一路回车用默认值或按需修改） npm init -y # 3. 安装 oh-my-codex 核心依赖 npm install oh-my-codex # 4. 手动创建基础目录结构（后续会详细说明）

执行npx create-oh-my-codex并完成交互后，进入项目目录，你会看到类似如下的结构：

my-first-codex-cli/ ├── package.json ├── tsconfig.json # TypeScript 配置 ├── src/ │ ├── commands/ # 命令目录（核心） │ │ └── index.ts # 命令入口 │ ├── templates/ # 模板目录（核心） │ │ └── default/ # 默认模板 │ └── index.ts # CLI 主入口文件 ├── bin/ # 可执行文件目录 │ └── cli.js # Node.js 可执行入口 └── .codexrc.json # oh-my-codex 配置文件

这就是一个最基础的oh-my-codex项目骨架。package.json里已经配置好了必要的脚本和依赖。接下来，我们深入核心，看看如何定义你的第一个命令。

4. 核心命令开发详解

4.1 命令类结构与生命周期

在src/commands/目录下，框架初始化时可能已经生成了一个index.ts。我们来看如何从头创建一个新的命令文件，例如src/commands/init.ts，它对应my-cli init命令。

// src/commands/init.ts import { Command } from 'oh-my-codex'; import type { ICommandContext } from 'oh-my-codex'; // 继承自框架的 Command 基类 export default class InitCommand extends Command { // 命令的名称，即用户在终端输入的 `init` name = 'init'; // 命令的描述，会显示在帮助信息中 description = 'Initialize a new project from a template'; // 定义命令参数。这里定义了一个必选参数 `projectName` args = [ { name: 'projectName', description: 'The name of the new project', required: true, // 必填 } ]; // 定义命令选项。例如 `--template` 用于指定使用的模板 options = [ { name: 'template', description: 'Specify which template to use', alias: 't', // 短选项 `-t` defaultValue: 'default', // 默认值 }, { name: 'force', description: 'Overwrite existing directory', alias: 'f', type: 'boolean', // 布尔类型选项，不需要值 } ]; // 命令的核心执行逻辑 async run(context: ICommandContext) { // 从 context 中获取用户输入的参数和选项 const { args, options } = context; const projectName = args.projectName; const templateName = options.template; const forceOverwrite = options.force; // 1. 检查目标目录是否存在，并根据 force 选项决定是否覆盖 const targetDir = path.join(process.cwd(), projectName); if (fs.existsSync(targetDir)) { if (!forceOverwrite) { // 交互式询问用户是否覆盖 const { overwrite } = await context.prompt({ type: 'confirm', name: 'overwrite', message: `Directory "${projectName}" already exists. Overwrite?`, default: false, }); if (!overwrite) { this.logger.warn('Operation cancelled.'); return; } } // 如果强制覆盖或用户确认，则删除旧目录 fs.removeSync(targetDir); } // 2. 记录开始信息 this.logger.info(`Creating project "${projectName}" using template "${templateName}"...`); // 3. 调用渲染引擎（核心步骤，下一节详述） try { await this.renderTemplate(templateName, targetDir, { // 传递给模板的变量 projectName, createdAt: new Date().toISOString().split('T')[0], }); this.logger.success(`Project "${projectName}" created successfully!`); } catch (error) { this.logger.error(`Failed to create project: ${error.message}`); // 出错时清理可能已创建的部分文件 if (fs.existsSync(targetDir)) { fs.removeSync(targetDir); } process.exit(1); } } }

这个InitCommand类展示了命令的基本结构。args和options定义了命令行接口，框架会自动为你生成帮助信息（my-cli init --help）。run方法是异步的，你可以在这里执行任何逻辑，包括文件操作、网络请求、调用其他服务等。

生命周期钩子：除了run，Command基类还提供了一些生命周期方法供你覆盖，例如beforeRun（在执行前调用，可用于验证环境）、afterRun（执行后调用，可用于清理或通知）。合理利用这些钩子能让你的命令逻辑更清晰。

4.2 注册命令与 CLI 入口

创建好命令类之后，你需要将它注册到 CLI 应用中。这通常在src/commands/index.ts文件中完成：

// src/commands/index.ts import InitCommand from './init'; // 可以导入更多命令... // import ListCommand from './list'; // 导出一个命令列表 export default [ new InitCommand(), // new ListCommand(), ];

然后，在 CLI 的主入口文件src/index.ts中，你需要创建Application实例并加载这些命令：

// src/index.ts import { Application } from 'oh-my-codex'; import commands from './commands'; // 创建应用实例，可以配置应用名称、版本、描述等 const app = new Application({ name: 'my-cli', version: '1.0.0', description: 'My awesome CLI tool built with oh-my-codex', }); // 注册所有命令 commands.forEach(command => app.register(command)); // 启动应用，解析 process.argv app.run().catch(error => { console.error('Fatal error:', error); process.exit(1); });

最后，别忘了在package.json中指定可执行文件的入口：

{ "name": "my-first-codex-cli", "bin": { "my-cli": "./bin/cli.js" } }

而bin/cli.js文件内容通常非常简单，就是调用编译后的 TypeScript 入口：

#!/usr/bin/env node // 这一行是 shebang，告诉系统用 Node.js 来执行这个脚本 require('../dist/index.js');

至此，一个完整的命令从定义、注册到可执行的流程就完成了。你可以运行npm run build（如果配置了 TypeScript 编译）然后通过node ./bin/cli.js init my-project来测试你的命令。更常见的做法是在开发时使用npm link将你的 CLI 工具链接到全局，然后直接使用my-cli init my-project。

5. 模板系统深度解析与高级用法

5.1 模板目录结构与渲染规则

模板是oh-my-codex的灵魂，它决定了最终生成项目的面貌。所有模板都存放在src/templates/目录下，每个子目录代表一个独立的模板。例如，src/templates/default/是默认模板，src/templates/react-app/可以是一个 React 项目模板。

一个典型的模板目录结构如下：

src/templates/default/ ├── package.json.ejs ├── README.md.ejs ├── src/ │ ├── index.ts.ejs │ └── utils/ │ └── helper.ts.ejs ├── __tests__/ │ └── index.test.ts.ejs └── .gitignore

关键点解析：

1. 文件扩展名：模板文件通常使用.ejs作为扩展名（因为默认引擎是 EJS）。但这不是强制的，你可以在配置中指定其他引擎。框架会识别这些扩展名并进行渲染。注意：如果文件名本身没有模板变量，你也可以直接使用原始文件名（如.gitignore），框架会原样复制。
2. 目录结构：模板中的目录结构会被完整地复制到目标目录。你可以在模板中创建任意深度的嵌套目录。
3. 特殊文件处理：有些文件需要特殊处理。例如，为了兼容性，模板中的.gitignore文件在渲染后会被重命名为.gitignore（去掉.ejs后缀）。框架通常内置了这些常见文件的处理逻辑。

5.2 EJS 模板语法与数据传递

EJS (Embedded JavaScript) 语法简单直观，在模板文件中，你可以使用以下标签：

• <%= value %>：输出转义后的值（用于安全输出 HTML）。
• <%- value %>：输出原始值（如果值是 HTML 字符串，会被渲染）。
• <% code %>：执行 JavaScript 代码，不输出（用于条件判断、循环等）。
• <%# comment %>：注释。

在命令的run方法中，我们调用this.renderTemplate时传递了一个对象{ projectName, createdAt }，这个对象就是模板的“数据上下文”。在模板文件中，你可以直接访问这些变量。

让我们看一个package.json.ejs的复杂例子：

{ "name": "<%= projectName %>", "version": "1.0.0", "description": "<%= description || 'A project generated by my-cli' %>", "main": "dist/index.js", "scripts": { "build": "tsc", "start": "node dist/index.js", "test": "jest" <% if (features.includes('lint')) { %>, "lint": "eslint src --ext .ts"<% } %> <% if (features.includes('docker')) { %>, "docker:build": "docker build -t <%= projectName %> ."<% } %> }, "keywords": [], "author": "<%= author %>", "license": "MIT", "dependencies": { "oh-my-codex": "^1.0.0" }, "devDependencies": { "@types/node": "^20.0.0", "typescript": "^5.0.0" <% if (features.includes('jest')) { %>, "jest": "^29.0.0", "@types/jest": "^29.0.0"<% } %> } }

在这个模板中，我们不仅使用了简单的变量插值（<%= projectName %>），还使用了条件判断（<% if (features.includes('lint')) { %>）。这意味着你可以在渲染时传递一个features数组，动态决定是否包含lint脚本和jest开发依赖。这种动态性使得单个模板可以适应多种不同的项目配置需求，非常强大。

5.3 高级模板技巧：过滤器、局部模板与文件操作

自定义过滤器：有时你需要对变量进行格式化后再输出。EJS 本身不支持过滤器，但你可以通过在数据上下文中传递工具函数来实现。例如，在命令中：

await this.renderTemplate(templateName, targetDir, { projectName, kebabCase: (str) => str.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase(), });

然后在模板中：<%= kebabCase(projectName) %>。

局部模板（Include）：对于重复的代码片段，你可以将其提取为单独的模板文件，然后在主模板中包含它。EJS 使用<%- include('partials/header.ejs') %>语法。你需要确保oh-my-codex的渲染引擎配置支持include（通常需要传递文件系统路径）。一种更灵活的方式是在命令层预先读取局部模板内容，将其作为字符串变量传递给主模板。

条件性生成文件：你可能希望根据用户选择，决定是否生成某个文件。这可以在命令的run方法中实现逻辑控制，而不是在模板内。例如：

if (options.includeDockerfile) { // 手动渲染并写入 Dockerfile 模板 const dockerfileContent = await this.renderTemplateToString('templates/docker/Dockerfile.ejs', data); fs.outputFileSync(path.join(targetDir, 'Dockerfile'), dockerfileContent); }

文件权限与二进制文件：对于需要执行权限的文件（如 shell 脚本），你可以在模板渲染后，使用fs.chmodSync来修改其权限。对于图片等二进制文件，不应使用文本模板引擎处理，而应直接复制。oh-my-codex的渲染方法通常只处理文本文件，你可以通过覆盖默认行为或手动复制来处理二进制文件。

6. 交互增强：用户提示与动态配置

一个友好的 CLI 工具离不开与用户的交互。oh-my-codex内置了基于 Inquirer.js 的交互式提示功能，让你可以轻松收集用户输入。

6.1 集成交互式提示

回顾之前InitCommand的run方法，我们使用了context.prompt来询问用户是否覆盖目录。context.prompt方法接受一个 Inquirer 问题对象或数组，并返回用户答案的 Promise。

让我们设计一个更复杂的交互场景：在初始化项目时，让用户选择项目类型、是否启用某些功能等。

async run(context: ICommandContext) { const { args } = context; const projectName = args.projectName; // 第一步：基础信息确认 const { projectType } = await context.prompt({ type: 'list', name: 'projectType', message: 'What type of project do you want to create?', choices: [ { name: 'Node.js Library', value: 'library' }, { name: 'Web Application (React)', value: 'react-app' }, { name: 'CLI Tool', value: 'cli' }, { name: 'Other (Basic)', value: 'basic' }, ], default: 'basic', }); // 第二步：根据项目类型，动态询问功能选项 let features = []; if (projectType === 'library' || projectType === 'cli') { const { selectedFeatures } = await context.prompt({ type: 'checkbox', name: 'selectedFeatures', message: 'Select additional features:', choices: [ { name: 'Unit Testing (Jest)', value: 'jest', checked: true }, { name: 'Linting & Formatting (ESLint + Prettier)', value: 'lint', checked: true }, { name: 'Git Hooks (Husky)', value: 'husky' }, { name: 'Docker Support', value: 'docker' }, ], }); features = selectedFeatures; } // 第三步：询问作者信息（可默认从 git config 获取） const gitUserName = await this.getGitConfig('user.name'); const gitUserEmail = await this.getGitConfig('user.email'); const { authorName, authorEmail } = await context.prompt([ { type: 'input', name: 'authorName', message: 'Author name:', default: gitUserName || '', }, { type: 'input', name: 'authorEmail', message: 'Author email:', default: gitUserEmail || '', }, ]); // 将所有收集到的数据传递给模板 const templateData = { projectName, projectType, features, author: `${authorName}${authorEmail ? ` <${authorEmail}>` : ''}`, year: new Date().getFullYear(), }; // ... 后续渲染逻辑 } // 一个辅助函数，用于获取 git 配置 private async getGitConfig(key: string): Promise<string | null> { try { const { stdout } = await execa('git', ['config', '--get', key]); return stdout.trim(); } catch { return null; } }

通过这种分步、条件式的提问，你可以构建出非常灵活和智能的 CLI 交互流程。Inquirer 支持多种问题类型：input（文本输入）、confirm（是/否）、list（单选列表）、checkbox（多选）、password（密码）等，足以覆盖绝大多数场景。

6.2 配置文件.codexrc.json的作用

除了运行时交互，oh-my-codex还支持通过配置文件.codexrc.json来预设一些默认行为或模板变量。这个文件通常放在你的 CLI 项目根目录，或者用户使用你的 CLI 时放在他们的项目目录。

.codexrc.json的配置可以覆盖或补充命令的默认选项。例如：

{ "defaultTemplate": "company-standard", "variables": { "companyName": "MyAwesomeCorp", "license": "Apache-2.0" }, "hooks": { "postRender": "npm install" } }

在你的命令代码中，可以读取这个配置：

import { loadConfig } from 'oh-my-codex'; async run(context: ICommandContext) { // 加载配置，可以指定配置文件路径，默认查找 .codexrc.json const config = await loadConfig(process.cwd()); const defaultTemplate = config?.defaultTemplate || 'default'; const globalVars = config?.variables || {}; // 将全局变量与本次运行的变量合并 const templateData = { ...globalVars, projectName: args.projectName }; // ... 使用合并后的数据渲染 }

配置的优先级通常是：命令行选项 > 项目本地.codexrc.json> 用户全局.codexrc.json> 命令默认值。合理利用配置文件，可以减少用户重复输入，提供更个性化的默认体验。

7. 调试、测试与发布你的 CLI 工具

7.1 本地调试与开发工作流

在开发oh-my-codexCLI 时，高效的调试至关重要。

1. 使用npm link进行全局测试：这是测试 CLI 最方便的方法。在你的 CLI 项目根目录下运行：

npm link

这会在全局node_modules中创建一个指向你当前项目的符号链接。然后，你可以在任何地方直接使用你定义的命令（例如my-cli）来测试。调试完成后，运行npm unlink -g my-first-codex-cli来解除链接。

2. 利用 Node.js 调试器：你可以在package.json的脚本中配置调试命令：

{ "scripts": { "dev": "ts-node src/index.ts", "debug": "node --inspect-brk bin/cli.js init my-debug-project" } }

运行npm run debug，然后打开 Chrome 浏览器，访问chrome://inspect，点击“Open dedicated DevTools for Node”，即可进行图形化断点调试。

3. 结构化日志输出：oh-my-codex的Command基类提供了this.logger对象，它有info,success,warn,error等方法，输出带颜色和前缀的日志，比直接用console.log更清晰。在开发时，确保关键步骤和错误都有适当的日志。

7.2 单元测试与集成测试策略

为 CLI 工具编写测试可以保证其可靠性，尤其是在模板渲染逻辑复杂时。

单元测试（命令逻辑）：使用 Jest 或 Mocha 等测试框架，测试你的命令类中的纯函数逻辑。例如，测试参数解析、模板数据准备函数等。你可以模拟ICommandContext对象。

// __tests__/commands/init.test.ts import InitCommand from '../../src/commands/init'; describe('InitCommand', () => { let command: InitCommand; let mockContext: any; beforeEach(() => { command = new InitCommand(); mockContext = { args: { projectName: 'test-project' }, options: { template: 'default' }, prompt: jest.fn(), logger: { info: jest.fn(), success: jest.fn(), error: jest.fn() }, }; }); it('should prepare correct template data', async () => { // 测试命令内部的数据处理逻辑 const data = command.prepareTemplateData(mockContext.args, mockContext.options); expect(data).toHaveProperty('projectName', 'test-project'); }); it('should prompt for overwrite if directory exists', async () => { // 模拟 fs.existsSync 返回 true jest.spyOn(fs, 'existsSync').mockReturnValue(true); // 模拟用户回答“否” mockContext.prompt.mockResolvedValue({ overwrite: false }); await expect(command.run(mockContext)).resolves.toBeUndefined(); expect(mockContext.logger.warn).toHaveBeenCalledWith('Operation cancelled.'); }); });

集成测试（完整的 CLI 执行）：这更复杂，但更接近真实场景。你可以使用execa在测试中实际运行你的 CLI 命令，并检查退出码、输出内容和生成的文件。

import { execa } from 'execa'; import path from 'path'; import fs from 'fs-extra'; describe('CLI Integration', () => { const cliPath = path.join(__dirname, '../../bin/cli.js'); test('init command creates project structure', async () => { const testDir = path.join(__dirname, 'temp-test-project'); // 确保测试目录干净 await fs.remove(testDir); // 执行 CLI 命令，模拟用户输入（如果需要） const { stdout, exitCode } = await execa('node', [cliPath, 'init', 'temp-test-project', '--force'], { cwd: __dirname, }); expect(exitCode).toBe(0); expect(stdout).toContain('created successfully'); expect(fs.existsSync(path.join(testDir, 'package.json'))).toBe(true); // 清理 await fs.remove(testDir); }, 30000); // 设置较长的超时时间 });

7.3 构建、打包与发布到 npm

开发完成后，你需要将 TypeScript 代码编译成 JavaScript，并打包发布，以便用户可以通过npm install -g your-cli-name安装。

1. 构建配置：确保你的tsconfig.json配置正确，输出目录（如dist）是干净的。通常需要配置compilerOptions中的outDir为dist，rootDir为src。在package.json中设置main和types字段指向dist目录下的文件。

2. 处理模板文件：模板文件（src/templates/）是纯文本资源，不需要编译。你需要在构建过程中将它们复制到dist目录。这可以通过在package.json的scripts中添加一个copy-templates命令，并使用cpx或copyfiles包来实现：

{ "scripts": { "clean": "rimraf dist", "copy:templates": "cpx \"src/templates/**/*\" dist/templates", "build": "npm run clean && tsc && npm run copy:templates", "prepublishOnly": "npm run build" } }

3. 发布到 npm：首先，确保你有一个 npm 账号，并在终端登录 (npm login)。然后：

# 1. 更新 package.json 版本号（遵循语义化版本控制） npm version patch # 或 minor, major # 2. 运行构建脚本（prepublishOnly 会自动运行） npm run build # 3. 发布到 npm registry npm publish --access public # 如果是 scoped package，可能需要 --access public

发布后，用户就可以通过npm install -g your-cli-name来安装你的工具了。

重要提示：在发布前，务必仔细检查package.json中的files字段，确保它只包含了需要发布到 npm 的文件（如dist,bin,README.md），而排除了src,__tests__,.gitignore等开发文件。这可以减小包体积，并避免泄露源代码。

8. 常见问题排查与性能优化实录

在实际开发和用户使用过程中，你肯定会遇到各种各样的问题。这里我总结了一些高频问题和解决方案。

8.1 安装与依赖问题

问题：安装oh-my-codex或相关依赖时网络超时或失败。

• 排查：首先检查网络连接。可以尝试切换 npm 源到国内镜像（如淘宝源）：npm config set registry https://registry.npmmirror.com。如果问题依旧，可能是某个特定包的问题，尝试删除node_modules和package-lock.json后重新安装。
• 心得：对于团队项目，建议将package-lock.json或yarn.lock提交到版本库，确保所有开发者依赖版本一致。使用npm ci命令进行持续集成环境的安装，比npm install更严格、更快。

问题：用户全局安装我的 CLI 后，运行命令提示“命令未找到”或权限错误。

• 排查：
  1. 检查package.json中的bin字段配置是否正确，以及bin目录下的入口文件是否有正确的 shebang (#!/usr/bin/env node) 和执行权限（在 Unix 系统上可能需要chmod +x bin/cli.js）。
  2. 全局安装后，npm 会在全局node_modules/.bin目录创建软链接。检查该目录是否在你的系统PATH环境变量中。通常npm或yarn会处理，但某些自定义环境可能需要手动添加。
  3. 在 Windows 上，有时需要以管理员身份运行命令行进行全局安装。

8.2 模板渲染错误

问题：模板渲染后，变量{{projectName}}没有被替换，或者替换成了undefined。

• 排查：
  1. 检查数据传递：确保在renderTemplate方法中传递的data对象包含了projectName属性。使用console.log或调试器检查data对象的内容。
  2. 检查模板语法：确认使用的是正确的定界符。EJS 默认是<% %>和<%= %>，如果你修改了配置，需要对应调整。
  3. 检查文件扩展名：确保模板文件以.ejs结尾（或你配置的其他引擎扩展名），否则框架可能不会将其作为模板处理。
• 心得：在复杂的模板中，可以先用一个简单的测试数据渲染，看是否能正确输出，以隔离是数据问题还是模板语法问题。

问题：渲染出的文件格式混乱，例如 JSON 文件缩进不对或字符串被错误转义。

• 排查：这通常是由于在模板中混合使用了<%=（转义输出）和<%-（原始输出）。对于 JSON 文件，你希望输出的是纯文本，所以应该使用<%=。但如果你在 JSON 值中嵌套了另一个需要渲染的变量，可能会引起混乱。
• 解决方案：对于复杂的 JSON 结构，考虑在命令层将整个 JSON 对象构建好，然后通过<%- JSON.stringify(data.packageJson, null, 2) %>一次性输出，而不是在 JSON 模板内做复杂的条件判断。

8.3 性能优化建议

当你的模板非常多或文件很大时，渲染速度可能会变慢。

1. 异步文件操作：确保在命令的run方法中，所有文件读写操作都使用异步 API（如fs.promises.readFile或fs-extra的异步方法），避免阻塞事件循环。
2. 并行渲染：如果多个模板文件之间没有依赖关系，可以考虑使用Promise.all并行渲染，而不是顺序执行。但要注意文件系统操作的并发限制。
3. 缓存模板内容：如果同一个模板在单次命令执行中会被多次渲染（通常不会），可以考虑将读取的模板内容缓存起来，避免重复的磁盘 I/O。
4. 减少模板复杂度：尽量避免在模板中编写过于复杂的 JavaScript 逻辑。将复杂的计算或数据转换移到命令层的 JavaScript/TypeScript 代码中，模板只负责简单的变量替换和条件展示。这样既提高了渲染性能，也使得模板更易于维护。

8.4 错误处理与用户体验

一个健壮的 CLI 工具必须有良好的错误处理。

• 捕获并友好提示：在run方法内部，使用try...catch包裹核心逻辑。捕获到错误时，不要只是抛出原始的异常堆栈，而是用this.logger.error输出一条清晰、对用户友好的错误信息，并可能给出解决建议。
• 输入验证：在命令开始执行逻辑前，先验证用户输入的参数和选项是否合法。例如，检查projectName是否符合命名规范（是否包含非法字符）。oh-my-codex的命令参数定义支持简单的required和type验证，但更复杂的验证需要在run方法中手动进行。
• 提供--help：充分利用框架自动生成的帮助信息。为你命令的每个参数和选项编写清晰、简明的description。好的帮助文档能减少用户出错的可能。
• 进度反馈：对于耗时较长的操作（如下载依赖、处理大量文件），使用this.logger.info或简单的进度条（可以集成ora这样的库）给用户反馈，让他们知道程序正在运行，而不是卡死了。

开发 CLI 工具是一个不断迭代的过程。从最简单的init命令开始，逐步添加更多功能（如list列出可用模板、update更新模板、config管理配置），你的工具会变得越来越强大。oh-my-codex提供的这套架构，能让你专注于创造价值，而不是陷入命令行解析和文件操作的细节泥潭。希望这篇指南能帮你顺利起步，打造出提升自己或团队效率的利器。如果在实践中遇到新的问题，不妨回头看看框架的官方文档和源码，很多时候答案就在其中。