企业官网建设流程全解析

做了这么多年前端，我越来越觉得“脚手架”这件事被太多人想复杂了。一提到脚手架，大家首先想到的是各种重型CLI，但你有没有遇到过这种尴尬：用官方脚手架初始化项目，装了一堆根本用不上的依赖；想按团队规范调整目录结构，又得去翻源码改配置，甚至还要eject。前端简易脚手架搭建这件事，恰恰就是为了解决“新项目初始化时不断复制粘贴、东改西改”这个最普遍的痛点。

这篇内容主要讲怎么从零手写一个轻量、够用的前端脚手架，不依赖那些重量级框架工具。我会把原理、完整实现、以及我在实际使用中踩过的那些坑都讲清楚。不管你是前端新手想搞懂脚手架背后的机制，还是带团队想做内部工程化基建，这篇都值得看看。相信我，自己写一个脚手架之后，你对项目初始化、模板渲染这些事的理解会完全不一样。

1. 放着现成脚手架不用，为什么非要自己写一个

很多人的第一反应是：有必要吗？社区里有那么多现成的脚手架，create系列或者各类generator，拿过来用不就行了？

我在前两年也是这么想的，直到有一次团队里密集地开了几个新项目，我发现大家做初始化这件事的方式高度统一：找老项目复制一份，然后开始删代码。删路由、删页面、删依赖、改项目名、改标题、换图标。运气好十分钟搞定，运气不好某个配置文件里残留了上个项目的痕迹，排查起来要命。

1.1 现成脚手架解决不了团队规范问题

官方脚手架解决的是“从零到一个能跑的项目”的问题，但团队真正需要的是“从零到一个符合我们规范的项目”。这两者差距非常大。

举个例子。官方脚手架生成的项目，目录结构是它自己定义的，代码风格是它默认的，依赖版本是它固定的。如果你团队用的是别致的lint规则、特殊的目录分层、统一的提交规范，那每次初始化之后仍然要手工调整一大堆东西。更麻烦的是，一旦官方脚手架调整了模板结构，你团队里的老司机还好，新来的同事照着文档生成的项目，可能跟你们现有项目的组织方式完全对不上。

这种情况下，一个几十行代码的简易脚手架，价值反而比那些大而全的方案要高得多。因为它把“规范”固化在了模板里，而不是停留在口头约定或者文档里。用脚手架生成的项目，天然就是符合规范的，不需要人再去记那些约定。

1.2 自己搭脚手架的真实成本没那么高

很多人不想自己搭，是觉得复杂度高。但实际上，一个能用起来的简易脚手架，核心代码可能也就一两百行。它不需要涉及复杂的算法，也不需要做包发布，只需要做好三件事：接收参数、收集配置、把模板内容渲染后写入目标目录。

这三件事分别对应三个非常成熟的库：commander处理命令行参数，inquirer处理交互式提问，ejs做模板渲染。剩下的就是Node.js本身的文件操作能力。我甚至见过有人用Shell脚本加sed替换实现过一版，也跑得挺好。

如果你正在做前端工程化相关的事情，或者团队里有重复性较高的项目初始化工作，自己搭一个脚手架的成本远比你想象的低，但收益是长期的。下面这张表是我当时对比几种方案之后的判断：

1.3 搭建脚手架的额外价值：理解工程化底层逻辑

抛开实用价值不谈，实现一个脚手架本身也是一次特别好的Node.js命令行编程实践。它会逼着你接触命令行参数解析、进程调用、文件系统递归操作、模板引擎渲染这些基础知识。这些知识平时在业务开发里未必用得到，但理解了之后，你再去看那些大型脚手架工具的实现原理，会发现其实都是同一个套路，只是多了些插件机制和远程拉取模板的能力。

所以关于“为什么自己写”，我的结论是：它不是用来替代官方脚手架的，而是用来补充它们覆盖不到的团队级初始化需求的。简易脚手架，重点在“简易”，但解决的是“标准”的问题。

2. 脚手架的本质：模板、配置和文件生成的三层结构

想清楚原理再动手，比直接抄代码重要得多。脚手架拆开来看，就是三样东西：一份模板、一组配置、一段生成逻辑。

2.1 模板目录：项目骨架的完整拷贝

脚手架的核心资产是模板目录。你希望新项目长什么样，就把它先做成一棵树放在template目录下面。比如我维护的模板结构大概是这样的：

template/ ├── src/ │ ├── api/ │ ├── assets/ │ ├── components/ │ ├── pages/ │ ├── router/ │ ├── store/ │ ├── styles/ │ ├── utils/ │ ├── App.ejs │ └── main.ejs ├── .eslintrc.ejs ├── .prettierrc.ejs ├── .gitignore ├── index.html.ejs ├── package.json.ejs └── vite.config.ejs

注意，这里很多文件带了.ejs后缀。这代表着这个文件是“模板文件”，里面会有需要被替换的占位内容。比如package.json.ejs里面会有类似这样的写法：

{ "name": "<%= projectName %>", "version": "0.1.0", "description": "<%= projectDescription %>", "scripts": { "dev": "vite --port <%= devPort %>", "build": "vite build", "lint": "eslint . --fix" } }

而那些不带.ejs后缀的文件，比如.gitignore，就是纯静态文件，复制过去就行。

2.2 配置收集：从用户那里拿到“变量”的值

模板里有一堆占位符，比如项目名、描述、端口号，这些值从哪来？两种来源：一种是用户在命令行里直接传的，比如create-app my-project；另一种是通过交互式问答，一问一答之间收集。

我倾向于把两种方式结合起来：提供了命令行参数就直接用，没提供就通过问答引导用户输入。收集到的信息最终会被组装成一个对象，在渲染模板时作为数据源。这个对象才是整个脚手架的“配置中枢”：

const config = { projectName: 'my-app', projectDescription: 'A frontend project', needRouter: true, needStore: true, cssScheme: 'less', devPort: 5173 };

之所以要做成结构化对象而不是零散变量，是因为渲染阶段所有模板文件都要依赖这个对象。模板里既能直接引用某个字段，也能用EJS的条件判断和循环来生成不同形态的代码。

2.3 生成逻辑：读取、渲染、写入三步走

模板和配置都有了，生成逻辑其实就是一个三步走的流程：读文件、渲染内容、写到目标位置。

但这三步如果处理不好，很容易出问题。原因是模板目录是一个树状结构，里面有嵌套目录、有静态文件、也有需要渲染的动态文件。你需要在递归遍历的过程中区分它们。

我最初的实现版本是这样的思路：

async function generate(templatePath, targetPath, data) { const items = await fs.readdir(templatePath); for (const item of items) { const srcPath = path.join(templatePath, item); const destPath = path.join(targetPath, item.replace(/\.ejs$/, '')); const stat = await fs.stat(srcPath); if (stat.isDirectory()) { await generate(srcPath, destPath, data); } else { if (item.endsWith('.ejs')) { const content = await fs.readFile(srcPath, 'utf-8'); const rendered = ejs.render(content, data); await fs.outputFile(destPath, rendered); } else { await fs.copy(srcPath, destPath); } } } }

这段代码虽然简单，但它体现了最关键的设计决策：用文件后缀来区分“需要渲染的文件”和“直接复制的文件”。这个约定让模板目录的维护变得非常直观，哪个文件需要动态化，就把后缀改成.ejs并在内容里加上占位符；不需要动态化，就保持原样。逻辑简单，团队成员也容易理解。

2.4 为什么用EJS而不是字符串拼接

我见过有人写脚手架用字符串拼接来生成代码，类似const content = "export const baseUrl = '" + config.apiHost + "'"。这种做法也不是不行，但一旦代码量上来，维护体验会很痛苦。

用模板引擎，核心好处是代码逻辑和模板内容分离。EJS里面支持<% if (needRouter) { %>这种条件判断，也支持<% for (...) { %>循环。比如在路由文件里，我需要根据用户是否选择某个功能模块来决定是否需要注册对应的路由，EJS可以这样写：

const routes = [ { path: '/', component: Home } <% if (needAboutPage) { %> ,{ path: '/about', component: About } <% } %> ];

这种能力在字符串拼接方案里几乎没法优雅实现。EJS模板本身还是合法可读的JS代码，不渲染的时候你也能大概看懂文件长什么样，调试成本低得多。

3. 从零实现脚手架：命令行入口、交互问答与文件生成的完整拆解

原理清楚了，接下来进入实操环节。这一节我会把整个脚手架的代码骨架贴出来，并且解释每一步的关键决策。你可以直接参照这份代码搭一个能用的版本，再根据自己的业务场景去改模板。

3.1 初始化脚手架工程本身

脚手架本身也是一个Node.js项目。我推荐的目录结构是这样的：

my-cli/ ├── bin/ │ └── index.js # 命令行入口 ├── lib/ │ ├── questions.js # 交互问题定义 │ ├── generate.js # 模板生成逻辑 │ └── utils.js # 公共方法 ├── template/ │ ├── javascript/ # 纯JS版本模板 │ └── typescript/ # TS版本模板 └── package.json

脚手架自己的package.json里面需要加一个bin字段，这是让命令能被全局执行的关键：

{ "name": "my-cli", "bin": { "my-cli": "./bin/index.js" }, "dependencies": { "chalk": "^4.1.2", "commander": "^9.4.1", "ejs": "^3.1.8", "fs-extra": "^10.1.0", "inquirer": "^8.2.4" } }

提示：inquirer从9.x开始变成了纯ESM包，在CommonJS项目里使用会比较别扭。如果你用的是CommonJS风格，建议锁定8.x版本；如果项目本身就是ESM，直接上最新版没问题。这里我按比较稳妥的CommonJS写法来演示。

然后在项目根目录执行npm link，这个命令会把脚手架命令链接到全局环境，之后在任意目录都能直接调用。

3.2 命令行入口：参数的解析与兜底

入口文件bin/index.js做的事情很简单：解析参数、引导问答、调起生成逻辑。我用commander来管理命令，同时注册一个init子命令，这样以后想扩展其他命令也方便：

#! /usr/bin/env node const { program } = require('commander'); const { prompt } = require('inquirer'); const chalk = require('chalk'); const { questions } = require('../lib/questions'); const { generate } = require('../lib/generate'); const { normalizeProjectName } = require('../lib/utils'); program .version('1.0.0') .description('A simple frontend scaffold'); program .command('init') .description('Create a new project from template') .argument('[projectName]', 'project name') .option('-t, --typescript', 'use TypeScript template') .option('-p, --port <port>', 'dev server port') .action(async (projectName, options) => { const initialAnswers = { projectName: projectName ? normalizeProjectName(projectName) : undefined }; const answers = await prompt(questions, initialAnswers); const mergedOptions = { ...answers, typescript: options.typescript || answers.typescript }; try { await generate(mergedOptions); console.log(chalk.green('\n Project created successfully!')); console.log(chalk.cyan(' Next steps:')); console.log(chalk.cyan(' cd ' + mergedOptions.projectName)); console.log(chalk.cyan(' npm install')); console.log(chalk.cyan(' npm run dev')); } catch (error) { console.error(chalk.red(' Generation failed:'), error.message); process.exit(1); } }); program.parse(process.argv);

这里面有个容易被忽略的细节：如果用户直接传了项目名，还需要做一次规范化处理。npm对包名有严格的限制，理论上不能用大写字母、不能有空格、不能以点开头。但用户可能输入中文名、带空格的目录名。我的做法是提供一个normalizeProjectName函数，把非法字符过滤掉，转成kebab-case风格：

function normalizeProjectName(name) { return name .trim() .toLowerCase() .replace(/[^a-z0-9-]/g, '-') .replace(/-+/g, '-') .replace(/^-|-$/g, ''); }

这样一来，哪怕用户输入了一个中文的项目名，生成的目录名和package.json里的name字段也一定是合法的。

3.3 交互问答：用提问驱动配置收集

问答模块的设计直接决定了脚手架易用性。我见过很多脚手架的问答环节冗长到让人想放弃，动不动就七八个问题。我的原则是：高频且影响项目结构的选项留下，低频选项用默认值或者后续自行修改。

一个基础的问答列表大概长这样：

const questions = [ { type: 'input', name: 'projectName', message: 'Project name:', default: 'my-app', validate: (input) => { if (!input.trim()) return 'Project name is required'; if (!/^[a-z0-9-]+$/.test(input.trim())) { return 'Project name can only contain lowercase letters, numbers and hyphens'; } return true; }, when: (answers) => !answers.projectName }, { type: 'input', name: 'projectDescription', message: 'Project description:', default: 'A frontend project' }, { type: 'list', name: 'cssScheme', message: 'Choose a CSS solution:', choices: ['less', 'scss', 'plain-css'] }, { type: 'confirm', name: 'needRouter', message: 'Need Vue Router?', default: true }, { type: 'confirm', name: 'needStore', message: 'Need Pinia?', default: true }, { type: 'number', name: 'devPort', message: 'Dev server port:', default: 5173, validate: (input) => input >= 1 && input <= 65535 } ];

注意我第一个问题用了when字段，判断条件是!answers.projectName。这就是前面提到的“命令行传了就直接用，没传才问”的兜底策略。用户如果在命令里写了项目名，这一个问题就不会出现，整个初始化流程会更顺畅。

3.4 生成逻辑：完整处理模板目录树

核心的generate函数在上文原理部分已经展示过基础版本，这里给出一个增强版本，加入了一些项目实践中必不可少的保护逻辑：

const fs = require('fs-extra'); const path = require('path'); const ejs = require('ejs'); const { spawn } = require('child_process'); const TEMPLATE_ROOT = path.resolve(__dirname, '../template'); async function generate(options) { const { projectName } = options; const targetDir = path.resolve(process.cwd(), projectName); // 检查目标目录是否已存在 if (await fs.pathExists(targetDir)) { throw new Error(`Directory ${projectName} already exists. Please choose another name.`); } const templateDir = path.join( TEMPLATE_ROOT, options.typescript ? 'typescript' : 'javascript' ); // 递归生成文件 await renderDirectory(templateDir, targetDir, options); // 创建git仓库 await runCommand('git', ['init'], { cwd: targetDir }); // 询问是否继续执行包安装 await runCommand('npm', ['install'], { cwd: targetDir }); } async function renderDirectory(srcDir, destDir, data) { await fs.ensureDir(destDir); const items = await fs.readdir(srcDir); for (const item of items) { const srcPath = path.join(srcDir, item); const destName = item.replace(/\.ejs$/, ''); const destPath = path.join(destDir, destName); const stat = await fs.stat(srcPath); if (stat.isDirectory()) { await renderDirectory(srcPath, destPath, data); } else { const ext = path.extname(srcPath).toLowerCase(); // 二进制文件或带ejs标记的文件分开处理 if (item.endsWith('.ejs')) { const content = await fs.readFile(srcPath, 'utf-8'); const rendered = ejs.render(content, data); await fs.outputFile(destPath, rendered); } else if (isBinaryFile(ext)) { await fs.copy(srcPath, destPath); } else { const content = await fs.readFile(srcPath, 'utf-8'); await fs.outputFile(destPath, content); } } } } function isBinaryFile(ext) { return ['.png', '.jpg', '.jpeg', '.gif', '.ico', '.woff', '.woff2', '.ttf'].includes(ext); } function runCommand(command, args, opts) { return new Promise((resolve, reject) => { const child = spawn(command, args, { ...opts, stdio: 'inherit' }); child.on('error', reject); child.on('close', (code) => { if (code !== 0) { reject(new Error(`${command} exited with code ${code}`)); return; } resolve(); }); }); }

3.5 为什么这些设计决策是合理的

有几个设计上的取舍，我觉得值得展开讲讲逻辑。

首先是渲染和安装的先后顺序。很多脚手架生成完文件之后，只是打印一句“把目录切换到项目，然后自己npm install”。我觉得既然是脚手架，安装依赖这一步就应该帮忙做了，省得用户再多敲一次命令。但也注意，我说的是在文件全部生成完、且git仓库初始化完之后再执行install。这个顺序是刻意的：如果先执行install再生成文件，package.json可能还不存在，npm install会因找不到包描述文件而报错。如果把git init放在npm install之后，会把node_modules目录也纳入git的追踪范围，手动改.gitignore又显得多此一举。所以顺序是：先保证文件完整，再初始化git，最后装依赖。

其次是为什么要单独处理二进制文件。模板目录里如果放了favicon.ico、logo.png这类资源，直接拿ejs去渲染会发生什么？ejs会把整个文件当字符串解析，遇到二进制内容里的特殊字符就会报错，或者更糟的是静默地生成一个破坏的文件。所以我在renderDirectory里加了文件扩展名判断，属于图片字体类扩展名的，一律走fs.copy原样复制。这个坑，是我第一次打包模板时真实踩过的，不写下来的话后面的人可能还会踩一遍。

第三是child_process的spawn和exec的区别。我一开始图省事用exec执行npm install，遇到了Windows上命令长度超限的报错。后来改成了spawn加参数数组，就再也没出过问题。exec会把整个命令拼成一个字符串交给Shell去执行，参数里有特殊字符时很可能出幺蛾子；spawn直接把命令和参数分开传递，不经过Shell的解析，更稳定也更安全。

4. 用起来之后的真实问题清单：模板语法冲突、跨平台路径与二进制文件保护

脚手架写出来，能跑，这只能算完成了百分之六十。真正的打磨，是在各种真实使用场景里不断踩坑再补丁。这一节记几个我觉得最有代表性的问题，它们都不是“写不出来”的问题，而是“用过才知道”的问题。

4.1 EJS标签和项目代码之间的语法冲突

EJS默认使用<% %>作为标签包裹逻辑。但如果你模板里的某个文件内容本身包含了<%这个字符串（比如一些特殊格式的文档或内联的模板片段），EJS就会尝试解析它，随即抛错。

最大的真实冲突场景不是Vue项目里的{{ }}，那个和EJS完全不冲突。反而不太起眼的纯文本文件最危险。我举个实际例子：模板里有个README.md，里面是一段演示代码，代码里写了一行const plugin = '<% plugins.forEach(...) %>'，本意是展示一个伪代码示例，结果EJS把它当作真实标签去执行了。

解决方案有两个层面。一是约定：模板作者在写模板内容时，尽量减少<%这种组合的出现。二是更稳妥的做法：给EJS换一个自定义定界符，比如用[[ ]]或者{{ }}（如果目标框架不用这种语法的话）。EJS支持通过delimiter选项配置：

const rendered = ejs.render(content, data, { delimiter: '?' });

这样模板里的标签就变成<?= projectName ?>和<? if (needRouter) { ?>。虽然看起来不如默认标签熟悉，但和绝大多数前端框架的自定义模板语法可以彻底隔离，从根上避免冲突。我用了一段自定义定界符之后，再也没为这个问题头疼过。

4.2 模板文件的换行符问题

这个问题刚开始真的完全没意识到。在Windows上开发的同学用记事本风格的编辑器改过模板文件之后，文件的换行符可能变成CRLF。CRLF的换行符如果被提交进代码库，而团队其他人用的是macOS或Linux，那么Git会在diff里疯狂提示整行变更，因为每一行的行尾都被改了。

我的处理方式是在模板代码库根目录放一个.editorconfig文件，强制所有模板文件统一使用LF换行：

root = true [*] charset = utf-8 end_of_line = lf indent_style = space indent_size = 2 [*.ejs] end_of_line = lf

设置完之后，我在代码提交前再加一道保险：写一个简单的脚本扫描template目录，检查有没有包含CRLF的文件，有就直接报错。把这个问题挡在模板维护阶段，而不是等到用户生成项目之后才发现。

4.3 路径分隔符与跨平台兼容

这个更多是脚手架代码自身的问题。在拼接路径时，我见过有人图省事用templateDir + '/' + item这种字符串拼接方式，这在macOS和Linux上没问题，但在Windows上会得到类似template\src\components和template/src/components混用的路径，某些环节就会出问题。正确的做法是一律使用path.join。

另外还有一个容易被忽视的细节：spawn执行命令时，如果命令名是npm，在Windows上有时会找不到npm.cmd。这是个已知的Node.js行为差异。我现在要么用process.platform === 'win32'判断后给命令名加上.cmd后缀，要么直接调用npm-cli.js的路径。虽然有点丑，但胜在稳定。

4.4 自定义EJS定界符在团队中的可维护性

前面说到自定义定界符能解决语法冲突，但它也带来一个团队协作问题：模板维护者看到<?= name ?>可能一开始会愣一下，不习惯。所以我建议在template目录外面放一个template-guide.md，专门说明这个脚手架用了什么定界符、模板里哪些文件可以放逻辑、哪些文件要避免动态化。这个文档的成本极低，但能省去后来维护者大量的困惑时间。

我把这些问题按类型整理成了一张表，方便排查时快速对照：

5. 比脚手架本身更重要的：模板设计、多版本支持与迭代思路

代码层面的内容讲得差不多了，但脚手架能不能在团队里真正用起来，我觉得模板设计比脚手架代码更重要。代码只是生成机制，模板的质量决定了生成出来的项目长什么样。

5.1 模板文件也用上EJS的条件渲染能力

一个好的模板，不只是把项目名替换掉就结束了。它应该根据用户的选项，动态决定要不要生成某些文件。

比如我在模板里对package.json的scripts做了条件判断，用户没有选择less/scss时，不生成对应的脚本。又比如在入口文件main.ejs里，如果用户确认需要状态管理库，则自动生成对应的注册代码，否则干干净净地跳过：

import { createApp } from 'vue'; <% if (needStore) { %> import { createPinia } from 'pinia'; <% } %> import App from './App.vue'; const app = createApp(App); <% if (needStore) { %> app.use(createPinia()); <% } %> app.mount('#app');

这种能力是模板设计的灵魂。如果只是简单的“换名字”，那跟复制粘贴没什么区别。真正让脚手架有威力的，是它能根据不同的使用场景，生成出形态不完全一致的项目。

5.2 JS和TS双模板：一个选择，两种产出

我选择在template目录下直接分成javascript和typescript两个子目录，而不是做一个模板用EJS条件来控制。这样做的原因是，两者的差异不只是几个文件后缀，而是整个代码风格和依赖列表都有系统性差异。如果硬塞进一个模板，里面的条件分支会多到难以维护。

目录结构上留了两个入口，用户在选择模板类型时，我会根据选项动态决定读哪个目录。这样在模板维护层面看起来会有些重复，但每个模板内部的代码都保持简单纯粹，没有一堆互相干扰的条件判断，长期来看更划算。

5.3 脚手架在团队内的进化路径：从生成器到规范收口器

最后说一点更长远的。简易脚手架一旦用起来，它会慢慢从一个“项目生成器”进化成团队规范的“收口器”。

最开始，模板里放的是目录结构、基础依赖、lint配置，这是第一层。接下来你会发现，团队规范里那些“约定”也可以固化进来。比如提交信息格式、分支命名、代码格式化规则。脚手架可以在生成项目的时候，顺手把husky配置和commitlint配置一起生成好，新人在本地初始化完就自动具备这些约束。

再往后，如果团队有内部的组件库、请求封装库、埋点SDK，也可以把这些依赖和对应的初始化代码放进模板里。新人不需要知道“每个项目都要接一下埋点”这个隐含规则，因为脚手架已经帮他做了。这时候，脚手架的价值就不再只是省几分钟的复制粘贴，而是让所有新项目默认站在同一条高线上。

我自己的体验是，一个脚手架从不成熟到好用，靠的不是一开始就设计得多么宏大，而是每经历一次“啊，这个约定又有人忘了”的瞬间，就把它固化进模板。迭代几次之后，它自然就成熟了。当初花在那两三百行核心代码上的时间，早就在团队效率上成倍赚了回来。

如果你打算尝试，我的建议是：别一上来就想着做一个能应对所有场景的通用脚手架。先挑一个你最近要开工的项目，把它的骨架抽成模板，写一个最简单的生成器，跑通一次。然后在这个基础上慢慢加选项、加保护逻辑。脚手架这个东西，用起来才会知道哪里需要磨合，空想是想不出所有边界情况的。