Fuels CLI 脚手架全解析：玩转 `npm create fuels` 的命令行选项

npm create fuels 是 Fuel Network TypeScript SDK（fuels-ts）官方提供的全栈 dApp 脚手架工具，一条命令即可生成包含 Sway 合约、TypeScript 前端与本地开发链的完整项目骨架。本文以 Options 文档 为主体，结合 create-fuels 包源码 逐项拆解该命令支持的 CLI 选项、交互式流程与底层行为，让你在创建 Fuel dApp 时对每个参数都了然于胸。读完本文，你将能熟练运用模板选择、详细日志、依赖跳过等选项，精准定制自己的初始项目。

命令基本形态

npm create fuels 接受一个可选的项目名称位置参数，以及若干命令行选项，完整语法如下：

pnpm create fuels [project-name] [options]

npm create fuels -- [project-name] [options]

bun create fuels [project-name] [options]

需要留意的是，使用 npm 时 -- 用于将后续参数透传给脚手架工具本身；而 pnpm、bun 的原生 create 语法无需额外分隔符。仓库中 create-fuels 的实际发布版本以 {{fuels}} 占位符动态注入文档（见 versions.data.ts），因此你也可以通过 @版本号 显式指定工具版本，例如 npm create fuels@<版本号> -- my-app --template nextjs。

从底层实现看，该 CLI 基于 commander 构建，setupProgram.ts 中注册了位置参数 [projectDirectory] 与全部选项；入口 bin.ts 解析 process.argv 后交给 cli.ts 的 runScaffoldCli 执行脚手架流程。

各选项速查表

create fuels 当前暴露的 CLI 选项可汇总如下（除表中注明外均为长选项形式）：

选项	作用	取值/默认值
[project-name]（位置参数）	指定项目目录名	不传时进入交互式询问
--template <template-name>	指定项目模板	vite（默认）、nextjs
--no-install	跳过依赖安装与类型生成	默认会安装依赖
--verbose	开启详细日志输出	布尔开关，默认关闭
-h, --help	显示帮助信息（含全部可用选项）	—
-V, --version	显示 npm create fuels 工具自身版本号	—

下面对每个选项逐一深入讲解。

位置参数 [project-name]：项目命名与交互式兜底

项目名称既可以跟在命令后直接给出，也可以在交互提示中填写。若命令行中未提供项目名，工具会调用 prompts 库弹出交互式问题：

◇ What is the name of your project?
│ my-fuel-project
└

对应源码位于 promptForProjectPath.ts，默认建议值为 my-fuel-project；若用户在交互中取消（Ctrl+C），进程会直接退出。

脚手架对项目路径做了两层防护校验（见 cli.ts）：

1. 若目标目录已存在，会报错 A folder already exists at ${projectPath}. Please choose a different project name. 并重新询问；
2. 若返回的路径为空字符串，会提示 Please specify a project directory. 并要求重试。

两条循环逻辑中都有 process.env.VITEST 环境变量的特殊分支——在仓库测试环境下直接抛出异常以避免进程挂起，这印证了项目自身的测试设计（详见 cli.test.ts 相关用例思路）。

项目创建成功后，控制台会输出形如下文的结果信息，并给出下一步命令指引（cd 进目录、启动本地 Fuel 开发服务、运行前端）：

⚡️ Success! Created a fullstack Fuel dapp at my-fuel-project

To get started:

- cd into the project directory: cd my-fuel-project
- Start a local Fuel dev server: pnpm fuels:dev
- Run the frontend: pnpm dev

--template <template-name>：选择前端框架模板

该选项用于指定生成项目的模板。可选模板为 vite 与 nextjs，默认值为 vite。在源码中，模板以 Set 形式集中注册（setupProgram.ts）：

export type Template = 'nextjs' | 'vite';
export const templates: Set<Template> = new Set(['nextjs', 'vite']);
export const defaultTemplate: Template = 'vite';

而选项的默认值也由 commander 在此处统一指定：

.option('--template <template>', 'Specify a template to use', defaultTemplate)

模板的实际内容存放于仓库根目录 templates/ 下，分别对应 templates/vite 与 templates/nextjs 两个目录，每个模板都自带 sway-programs/（Sway 程序）、前端源码、fuels.config.ts、package.json、fuel-toolchain.toml 以及 Playwright/Vitest 测试骨架等完整工程文件。脚手架执行时会：

1. 通过 doesTemplateExist 校验模板名是否合法（doesTemplateExist.ts）；
2. 若不存在则报错并列出全部可用模板后退出（cli.ts）；
3. 合法则把模板目录递归拷贝到新建项目路径下（过滤掉 CHANGELOG.md），再执行 gitignore → .gitignore、env → .env.local 等重命名适配（cli.ts）。

从源码结构与测试可以确认，--template nextjs 与默认模板在参数解析上无差别（见 setupProgram.test.ts）。选模板与不选时的推荐组合命令：

# 使用默认的 Vite 模板
pnpm create fuels my-vite-app

# 显式指定 Next.js 模板
pnpm create fuels --template nextjs my-next-app

# 等价写法（npm 需要 -- 分隔）
npm create fuels -- --template nextjs my-next-app

需要说明的是，无论选哪种模板，生成的都是“全栈”Fuel dApp——既包含前端，也包含 Sway 合约/脚本/谓词程序及对应的 fuels.config.ts 配置，模板差异主要体现在前端框架与工程构建上。

--verbose：开启详细日志

--verbose 用于开启详细（verbose）日志输出，在排查脚手架工具自身问题时尤其有用。底层注册代码为：

.option('--verbose', 'Enable verbose logging')

其核心影响体现在依赖安装阶段：当该选项开启时，cli.ts 中以 stdio: verboseEnabled ? 'inherit' : 'pipe' 方式执行 pnpm/npm/bun install 与 prebuild（类型生成）命令——即开启后会把包管理器的完整输出直接透传到终端，方便你观察每一步在做什么；默认关闭时则只展示 ora 进度动画（Copying template files..、Installing dependencies..）与最终成败结果。

--no-install：跳过依赖安装与类型生成

该选项在仓库源码中实际存在（setupProgram.ts），用于指示工具不要自动安装依赖。注意 commander 的 --no-* 语法意味着对应字段 install 默认值为 true，即“默认会安装依赖”，仅在显式传入 --no-install 时关闭：

.option('--no-install', 'Do not install dependencies')

这一默认行为同样被单元测试锁定（见 setupProgram.test.ts 中 expect(program.opts().install).toBe(true) 与 --no-install 后 toBe(false) 的断言）。由于安装依赖与后续 prebuild 类型生成共用同一个 if (opts.install) 分支（cli.ts），因此 --no-install 会同时跳过依赖安装与 Sway 类型文件的自动生成，适合只想拿到纯净项目骨架、后续自行手动安装的场景。

pnpm create fuels my-app --no-install

-h, --help 与 -V, --version：内置帮助与版本信息

• -h, --help：展示包含全部可用选项的帮助信息。由于程序配置了 .showHelpAfterError(true)（setupProgram.ts），当参数解析出错时也会自动追加输出帮助文本，引导使用者自查；
• -V, --version：显示 npm create fuels 命令自身的版本号。它来源于 .version(packageJson.version)（setupProgram.ts），即 create-fuels/package.json 中的 version 字段。利用它可以在出问题时快速核对所用工具版本，便于对齐仓库 CHANGELOG.md 中的版本说明。

这两个选项由 commander 依据 .arguments(...)、.version(...) 配置自动生成，无需手写解析逻辑。

参数解析与执行的完整调用链

综合来看，一次 pnpm create fuels my-app --template nextjs 的底层执行链路可以概括为：

1. bin.ts 把 process.argv 传给 runScaffoldCli；
2. program.parse(args) 由 commander 解析位置参数与选项，产出 ProgramOptions（cli.ts）；
3. 依据选项确定模板（opts.template ?? defaultTemplate）并校验其合法性；
4. 解析出项目路径（位置参数或交互式输入），循环校验目录不冲突；
5. 检测实际使用的包管理器（npm_config_user_agent 自动识别 pnpm/npm/bun，见 getPackageManager.ts），并据此改写 package.json 与 README.md 中的脚本命令（如 pnpm run fuels:dev、npm run fuels:dev）；
6. 拷贝模板文件、处理 .gitignore/.env.local/Sway workspace TOML，随后按 install 开关决定是否安装依赖并生成类型。

值得强调的是，脚手架还会自动把 package.json 中的 fuels 依赖版本改写为当前实际使用的 create-fuels 版本（getPackageVersion + 字符串替换，见 cli.ts），确保生成项目与工具版本的一致性，避免脚手架模板与运行时 SDK 版本错位。

常见用法组合示例

以下汇总了几类贴近实际开发场景的命令组合：

# 1) 完全交互式：只敲命令，其余问题在提示中回答
pnpm create fuels

# 2) 指定项目名 + 默认 Vite 模板 + 安装依赖
pnpm create fuels counter-dapp

# 3) 显式使用 Next.js 模板
pnpm create fuels --template nextjs my-next-dapp

# 4) 只生成骨架，不自动安装依赖
pnpm create fuels --no-install --template vite my-dapp

# 5) 排障：开启详细日志
npm create fuels -- --template nextjs my-app --verbose

创建完成后，即可按脚手架提示启动开发环境：先运行 pnpm fuels:dev 拉起本地 Fuel 节点并持续编译/部署 Sway 程序，再于另一终端运行 pnpm dev 启动前端。若想进一步了解脚手架生成项目的目录结构、fuels.config.ts 的作用或如何向模板添加新的合约功能，可继续阅读 Creating a Fuel dApp 指南；关于 fuels.config.ts 各配置项细节，可查阅 Fuels CLI 的配置文件文档。