create-quasar 脚手架实战指南一条命令从零搭建 Quasar 应用与 App Extension【免费下载链接】quasarQuasar Framework - Build high-performance VueJS user interfaces in record time项目地址: https://gitcode.com/gh_mirrors/qu/quasar本指南以 Quasar 官方脚手架工具 create-quasar 为核心讲解如何通过npm init quasar、pnpm create quasar等一行命令快速生成 Quasar CLI 项目SPA、SSR、SSG、PWA、BEX、混合移动端与 Electron 应用以及 Quasar App Extension 的完整目录结构并深入其源码create-quasar 包剖析命令行参数、交互式提示、模板渲染与 Git 初始化等底层实现。读完本文你将掌握 create-quasar 的全部命令用法、预设组合策略以及脚手架背后的模板引擎与校验逻辑。create-quasar 是什么create-quasar 是 Quasar Framework 官方提供的项目脚手架工具对应本仓库中的 create-quasar 目录。它的定位非常明确用于scaffold Quasar CLI project folders即生成可直接开发运行的 Quasar 项目文件夹。它支持两种产出物App一个完整的 Quasar CLI 应用工程Vite 3 构建后续可用quasar dev开发、quasar build构建覆盖 SPA、SSR、SSG、PWA、浏览器扩展BEX、Cordova/Capacitor 移动应用与 Electron 桌面应用App ExtensionAEQuasar CLI 的扩展包骨架包含 prompts、install、uninstall 等生命周期脚本模板供开发者编写可分发、可复用的扩展。从 create-quasar/package.json 可以看到该包当前版本为5.0.27以create-quasar为 bin 入口指向bin/create-quasar.js采用 ESM 模块规范要求Node.js 20。其依赖包括clack/prompts交互式命令行提示、quasar/artCLI 横幅、quasar/update-notifier版本更新提醒、cross-spawn跨平台子进程、fs-extra文件系统操作、kolorist彩色输出与tinyglobby模板文件遍历这些依赖共同支撑了从提问到落盘再到安装依赖的完整链路。快速开始一行命令创建项目官方推荐的使用方式是通过各包管理器的create命令无需手动安装 create-quasar 本身npm init quasar # 或 yarn create quasar # 或 pnpm create quasar # 或 bun create quasar其中pnpm create quasarlatest、npm init quasarlatest、bun create quasarlatest会显式拉取最新版本。执行后CLI 会依次询问以下问题详见 create-project-folder.jsWhat would you like to build?—— 选择App with Quasar CLI, lets go!或AppExtension for Quasar CLI。注意App Extension 仅允许使用 pnpm若当前并非通过 pnpm 调用该选项会被禁用并提示改用pnpm create quasarlatestProject folder:—— 输入项目目录名默认为quasar-project直接回车即生成在当前目录下的同名子目录若输入.则生成在当前目录Package name / AE ext-id—— App 询问 npm 包名AE 询问扩展标识无需带quasar-app-extension-前缀Project product name—— 应用产品名构建移动端应用时必须以字母开头默认Quasar AppPick features—— 以多选方式勾选预设TypeScript、Sass、Linting、filename-based routing、Pinia、i18n 等Install project dependencies?—— 选择用哪个包管理器安装依赖或暂不安装。脚手架完成后终端会打印To get started提示通常为cd project-folder pnpm install pnpm run lint # 若启用了 lint 预设 pnpm run dev # 或 quasar dev检测当前使用的包管理器脚手架会通过 running-pm.js 解析环境变量npm_config_user_agent判断你是在哪个包管理器下调用的const pm process.env.npm_config_user_agent export const runningPackageManager pm?.split( )[0].split(/)[0]这一检测结果直接影响两个行为一是依赖安装时的默认选项通过 pnpm 调用时默认推荐 pnpm二是--install参数的类型解析——通过包管理器调用时它是布尔开关直接执行create-quasar二进制时则是一个可指定包管理器名的字符串参数。另外只有当runningPackageManager为空即直接运行二进制时才会触发quasar/update-notifier的更新检查避免在pnpm create等场景下重复提示。命令行选项详解--help 全参数在 bin/create-quasar.js 中CLI 基于 Node 内置的parseArgs实现了完整的参数解析支持位置参数项目目录与下列选项。执行create-quasar --help即可在终端看到全部说明选项简写类型说明--template-tstring项目类型app或ae--overwrite-oboolean目标目录已存在时覆盖其中文件--preset-pstring可多次应用预设app 支持typescript、sass、oxlint、eslint、i18n、pinia、fbrfilename-based routingae 支持typescript、oxlint、prompts、install、uninstall--namestring项目在 package.json 中的包名必须是合法 npm 包名--authorstringpackage.json 中的作者字段--no-gitboolean不初始化 Git 仓库--install-i布尔/string通过包管理器调用时为布尔如--install直接运行时指定包管理器--install pnpm/yarn/npm/bun--productstring仅app模板可用产品名--defaults-dboolean其余未指定选项全部使用默认值跳过交互提问--no-colorboolean关闭彩色输出--help-hboolean显示帮助信息--version-vboolean输出版本号5.0.27典型组合示例来自源码中的 help 文案create-quasar my-app --template app --defaults create-quasar my-ae --template ae --preset prompts --preset oxlint --defaults参数校验与约束源码对参数做了严格校验理解这些约束可以避免踩坑模板只能是app或ae否则报错Invalid template specified--product仅适用于 app用在 ae 上会直接报错要求移除oxlint 与 eslint 互斥不能同时使用oxlint and eslint cannot be used together二者任选其一会被转换为内部linting预设并记录scope.linter位置参数最多一个项目目录多余会报错未提供时若启用了--defaults则默认使用目录名quasar-project包名合法性由 utils.js 中的definitions.name校验长度不超过 214、不能是node_modules且必须匹配/^(?:[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/支持scope/name形式的 scoped 包名ae 模板强制 pnpm通过包管理器调用时若不是 pnpm--install会报错 Use only pnpm直接运行时--install也只接受pnpm--defaults的默认预设app 为sassoxlintae 为promptsinstalluninstalloxlint且默认安装工具均为 pnpm位置参数提供的目录名还会自动派生出默认包名转小写、空格转-、剔除非法字符见 utils.js 的definitions.name.default。防止在 Quasar 项目内误执行ensure-outside-project.js 会从当前目录逐级向上查找quasar.config.js、quasar.config.mjs、quasar.config.ts、quasar.config.cjs及历史遗留的quasar.conf.js一旦发现即判定当前位于 Quasar 项目内部并直接退出This command must NOT be executed inside of a Quasar project folder.。因此在已有 Quasar 项目内运行 create-quasar 是无效的请始终在空目录或项目外部执行。交互式流程与目录处理create-project-folder.js 编排了整个交互流程其中几个关键细节值得关注。非空目录的处理若目标目录已存在且非空且未指定--overwriteCLI 会先确认Target directory is not empty. Remove existing files and continue?。选择否会取消脚手架选择是则进入覆盖模式。覆盖时 utils.js 的createTargetDir会清空目录内容但特意保留.git文件夹注释明确说明这是为了让用户overwrite their files, not to lose repo history——覆盖文件但保留 Git 历史。若配合--defaults使用则不会提问直接报错提示改用--overwrite。依赖安装与 lint选择安装依赖后CLI 会在新项目目录内依次执行pnpm install或所选包管理器与pnpm run lint。源码对 pnpm 做了专门适配设置环境变量PNPM_CONFIG_STRICT_DEP_BUILDSfalse注释解释这是因为 pnpm 11 会在依赖树中存在未批准的构建脚本时以错误码退出pnpm 10 仅为警告若不放开会误判新项目安装失败。安装失败时 CLI 会提示可能是 npm registry 临时问题并将install标记为 false转而把pnpm install作为后续建议命令打印出来。Git 初始化默认情况下除非传入--no-git脚手架会在新项目中执行 Git 初始化utils.js 的initializeGit系统未安装 Git 则跳过并提示父目录已是 Git 仓库则跳过避免嵌套仓库初始化时若用户未配置init.defaultBranch会显式使用git -c init.defaultBranchmain init固定初始分支为main执行git add -A并提交提交信息为Initialize the project 带--no-verify跳过钩子检测到用户开启了 GPG 签名时会提示waiting for GPG signing避免用户误以为卡死。App 模板预设组合与目录生成App 模板的脚手架脚本位于 templates/app/create-quasar-script.js其下又分派给 templates/app/vite-3/create-quasar-script.js 执行生成逻辑如下const dir scope.preset.typescript ? ts : js utils.createTargetDir(scope) utils.renderTemplate(${dir}/BASE, scope) const css scope.preset.sass ? sass : css utils.renderTemplate(${dir}/${css}, scope) if (scope.preset.i18n) utils.renderTemplate(${dir}/i18n, scope) if (scope.preset.pinia) utils.renderTemplate(${dir}/pinia, scope) if (scope.linter oxlint) utils.renderTemplate(${dir}/oxlint, scope) else if (scope.linter eslint) utils.renderTemplate(${dir}/eslint, scope) utils.renderTemplate( scope.preset.fbr ? ${dir}/filenameBasedRouting : ${dir}/manualRouting, scope )可以看到预设与模板片段一一对应且可自由叠加BASE无论 JS 还是 TS 都必装的骨架包含.vscode配置含mcp.json、public/icons图标、src目录assets、boot、components/EssentialLink.vue、App.vue、index.html、quasar.config.js/.ts、postcss.config.js、jsconfig/tsconfig等见 create-quasar/templates/app/vite-3/js/BASEcssvssass二选一前者生成src/css/app.css后者额外生成quasar.variables.scss供 Quasar 主题变量定制oxlintvseslint二选一的 lint 方案oxlint oxfmt 或 ESLint Prettier并附带对应配置文件fbrvsmanualRoutingfilename-based routing按src/pages文件结构自动生成路由含(index).vue、[...path].vue等约定式文件与手写routes.js的传统路由二选一pinia加入src/stores与示例 storei18n加入src/boot/i18n.js与src/i18n/en-US语言包。模板中所有以下划线_开头的文件如_package.json、_jsconfig.json、_gitignore在渲染时会被自动去除下划线前缀这是模板引擎的约定_前缀表示该文件内容需要经过模板插值处理输出时还原为标准文件名见 utils.js 的renderTemplate。同时.json文件在插值后会尝试JSON.stringify(..., null, 2)重新格式化保证生成的配置可读若 JSON 中含注释导致解析失败则原样保留。App Extension 模板专为扩展作者设计AE 模板的脚本位于 templates/ae/create-quasar-script.js与 App 最大的差异在于包名语义输入的 ext-id 会被解析为完整包名自动补上quasar-app-extension-前缀function parsePackageName(name) { const scopedPackageRegex /^([^/])\/([^/])$/ const normalizedName name .replace(/^quasar-app-extension-/, ) .replace(/^([^/]\/)quasar-app-extension-/, $1) ... }即输入my-ext会生成包名quasar-app-extension-my-ext输入my-org/my-ext则生成my-org/quasar-app-extension-my-ext。交互式多选按分组呈现ToolingTypeScript support、Linting Formattingoxlint oxfmt推荐Additional AE ScriptsPrompts script、Install script、Uninstall script对应 App Extension 生命周期钩子。生成结果包含完整的扩展骨架src/index.js扩展入口、src/runtime/运行时注入代码如注册组件与 boot 文件、src/templates/扩展自带的模板目录、playground/用于本地联调扩展效果的宿主 App含quasar.extensions.json、以及 install/prompts/uninstall 脚本目录见 create-quasar/templates/ae/js。AE 项目内还附带pnpm-workspace.yaml配合 playground 使用 workspace 协议进行本地开发。脚本最后会把scope.packageManagerList强制置为[pnpm]从机制上保证 AE 只支持 pnpm。底层原理内置的模板渲染引擎create-quasar 没有依赖通用的模板引擎而是在 lib/template.js 中内置了一个受 Eta v4.5.1 启发实现的轻量模板编译器这是理解脚手架如何把参数写进文件的关键。其语法基于%与%标签可通过rawOpts定制支持三种块类型% ... %执行任意 JS 语句无前缀编译为函数体内代码% expr %插值输出interpolate等价于拼接expr的结果%~ expr %原始输出raw不经过转义适合输出代码片段。核心编译流程为getAST将模板字符串解析为 AST字符串块与代码块交替compileBody把 AST 编译为一段拼接__qstr__累加器的函数体最终通过new Function(varName, body)生成渲染函数compileTemplateToFn或导出为 ESM 模块字符串compileTemplateToFile。解析器对引号字符串、模板字面量与块注释做了跳转处理遇到、、、/*会跳过其内容并支持-、_形式的空白修剪避免模板标签周围出现多余换行。以_package.json为例模板中形如name: % name %的占位符最终会被替换为校验过的包名scope中的所有字段name、product、author、aeFullName等都会注入渲染作用域。渲染结果随后写入目标目录这整个过程被 utils.js 的renderTemplate封装先用tinyglobby递归遍历模板片段再逐个处理文件。测试与验证该脚手架质量由两层测试保障均可在 create-quasar/test 下查看单元测试template.test.js模板编译器的 AST 解析与渲染正确性、utils.test.js包名校验、目录清理、Git 初始化等工具函数、running-pm.test.js包管理器检测、ensure-outside-project.test.jsQuasar 项目检测、cli.test.js命令行参数解析与校验端到端测试test/e2e/app.test.js与test/e2e/ae.test.js配合local-registry.js本地 npm registry真实执行脚手架并验证生成的项目可以安装依赖、通过 lint。运行方式见 create-quasar/package.json 中的脚本pnpm test:unit、pnpm test:e2e:app、pnpm test:e2e:ae。这些测试与仓库根目录的 CONTRIBUTING.md 共同构成了参与 Quasar 生态开发的质量基线。常见问题与排查提示 This command must NOT be executed inside of a Quasar project folder你正在某个 Quasar 项目目录内运行脚手架请切换到其他目录见 ensure-outside-project.js 的向上遍历检测逻辑AE 选项被禁用/报错 Use only pnpmApp Extension 模板仅支持 pnpm请改用pnpm create quasarlatest并选择 AE目标目录非空交互模式下会征询是否清空--defaults模式下则必须显式加--overwrite且覆盖会保留.git历史依赖安装失败可能为 npm registry 临时问题脚手架会回退为提示手动执行pnpm installpnpm 场景下已内置PNPM_CONFIG_STRICT_DEP_BUILDSfalse规避构建脚本审批导致的误报--preset组合无效oxlint 与 eslint 互斥--preset oxlint --preset eslint会直接报错合法的 app 预设仅typescript、sass、oxlint、eslint、i18n、pinia、fbr--product报错该选项仅适用于--template app创建 AE 时请移除。小结create-quasar 以一条命令 交互问答 预设组合的方式把 Quasar 项目的初始化成本压缩到极致App 模板覆盖从纯 JS 到 TypeScript、从手动路由到 filename-based routing、从 CSS 到 Sass、从 oxlint 到 ESLint 的完整组合矩阵AE 模板则为扩展作者提供了带生命周期脚本与 playground 的标准骨架。其背后是自研的 Eta 风格模板引擎、严谨的参数校验、包管理器探测与 Git 自动化等工程细节。结合本仓库源码create-quasar/bin/create-quasar.js、create-quasar/lib/utils.js、create-quasar/lib/template.js阅读可以完整复现并深入理解这套脚手架机制的每一个环节。【免费下载链接】quasarQuasar Framework - Build high-performance VueJS user interfaces in record time项目地址: https://gitcode.com/gh_mirrors/qu/quasar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考