Quasar CLI with Vite 项目目录结构全解析：从 src 到 dist 的每个目录与文件-平芜编程栈

前端
UI组件
跨平台

【免费下载链接】quasar

Quasar Framework - Build high-performance VueJS user interfaces in record time

项目地址：https://gitcode.com/gh_mirrors/qu/quasar

Quasar Framework（本仓库即 Quasar 官方 monorepo）的@quasar/app-vite工具链会为每个应用生成一套约定优于配置的目录结构。本文以 docs/src/pages/quasar-cli-vite/directory-structure.md 为骨架，结合 create-quasar/templates/app/vite-3 中的真实脚手架模板与 app-vite/templates/entry/app.js 的入口装配源码，逐一解释每个目录和文件的职责、与源码的对应关系以及实际使用要点。读完本文，你将能对任何 Quasar（Vite 版）项目"按图索骥"，快速定位组件、路由、状态管理与各平台模式代码的归属位置，也能理解为什么"所有模式都装上"的完整结构看起来庞大却并不可怕。

一、整体视角：这是一棵"可裁剪"的树

原文开篇即指出：下图展示的是**安装了全部模式（mode）**的项目结构——SPA、SSR、SSG、PWA、Capacitor、Cordova、Electron、BEX（浏览器扩展）对应的src-*目录全部在场。真实项目中，只有你通过quasar mode add <mode>启用过的模式才会出现对应目录，因此无需被完整形态吓到。

下面是将原文档的交互式目录树转写为可阅读的完整结构（标注了每个节点的核心职责）：

<project-root>/ ├── public/ # 纯静态资源，原样拷贝进构建产物 ├── src/ # 应用源码（Vite 处理的核心目录） │ ├── assets/ # 动态资源，由 Vite 加工（打包/指纹化） │ ├── components/ # 页面与布局中使用的 .vue 组件 │ ├── css/ │ │ ├── app.sass # 应用级全局样式入口（亦可是 app.scss/app.css） │ │ └── quasar.variables.sass # Quasar Sass 变量（可覆盖主题色等） │ ├── layouts/ # 布局 .vue 文件 │ ├── pages/ # 页面 .vue 文件 │ ├── boot/ # Boot 文件（应用初始化代码，相当于"多个 main.js"） │ ├── router/ │ │ ├── index.js # （或 .ts）Vue Router 定义 │ │ ├── routes.js # （或 .ts）应用路由表 │ │ └── typed-router.d.ts# 仅 TypeScript + filenameBasedRouting 启用时生成 │ ├── stores/ │ │ ├── index.js # （或 .ts）Pinia 初始化 │ │ └── <store>... # 各业务 store 定义 │ └── App.vue # 应用的根 Vue 组件 ├── src-ssr/ # SSR 专属代码（如生产环境 Node.js 服务器） ├── src-ssg/ # SSG 专属代码（如 ssg-renderer 脚本） ├── src-pwa/ # PWA 专属代码（如 Service Worker） ├── src-capacitor/ # Capacitor 生成的目录，用于构建移动应用 ├── src-cordova/ # Cordova 生成的目录，用于构建移动应用 ├── src-electron/ # Electron 专属代码（如主进程） ├── src-bex/ # BEX（浏览器扩展）专属代码（如后台脚本） ├── dist/ # 生产构建产物目录 │ ├── spa # 示例：构建 SPA 时的输出 │ ├── ssr # 示例：构建 SSR 时的输出 │ ├── electron # 示例：构建 Electron 时的输出 │ └── ... ├── quasar.config.js # （或 .ts）Quasar 应用配置文件（核心） ├── index.html # index.html 的模板文件 ├── .gitignore # Git 忽略路径 ├── .editorconfig # 跨编辑器统一风格配置 ├── eslint.config.js # ESLint 配置（扁平化配置） ├── postcss.config.js # PostCSS 配置 ├── jsconfig.json # 非 TypeScript 项目的编辑器配置 ├── tsconfig.json # TypeScript 配置 ├── env.d.ts # 仅 TypeScript 项目 ├── package.json # npm 脚本与依赖声明 └── README.md # 项目/站点说明文档

这份结构在仓库中的"权威模板"位于 create-quasar/templates/app/vite-3/js/BASE（JS 版）与 create-quasar/templates/app/vite-3/ts/BASE（TS 版），创建项目时由create-quasar脚手架据此生成。下文逐层拆解。

二、src/：应用源码的主战场

src/是开发者日常接触最多的目录，Vite 的模块打包、热更新、构建都围绕它展开。目录内路径可通过@/别名导入（例如@/components/MyComponent.vue指向src/components/），从 create-quasar 模板中的路由文件可看到@/layouts/MainLayout.vue、@/pages/IndexPage.vue的典型用法。

2.1 assets/：交给 Vite 处理的"动态"资源

src/assets/存放会被 Vite 参与编译的资源（图片、字体、SVG 等）。资源经导入（import img from '@/assets/logo.png'）后，Vite 会依据构建配置进行压缩、指纹化命名等处理，产物进入dist。与此相对，public/下的文件不做任何处理、原样拷贝。二者的取舍详见 docs/src/pages/quasar-cli-vite/handling-assets.md。模板中默认放置的示例资源为quasar-logo-vertical.svg。

2.2 components/、layouts/、pages/：三层视图组织

components/：可复用的 .vue 组件，被页面与布局引用；
layouts/：布局组件，承载全局 UI 骨架（顶栏、侧边抽屉、页脚等）；
pages/：路由对应的页面组件。

三者关系在 manualRouting 模板中体现得最直观：路由component指向 Layout，Layout 内部用<router-view />渲染子路由对应的 Page：

const routes = [ { path: '/', component: () => import('@/layouts/MainLayout.vue'), children: [ { path: '', component: () => import('@/pages/IndexPage.vue') }, { path: 'second', component: () => import('@/pages/SecondPage.vue') } ], }, // 始终放在最后：兜底 404 路由 { path: '/:catchAll(.*)*', component: () => import('@/pages/ErrorNotFound.vue'), } ]

而 MainLayout.vue 模板展示了布局的骨架：<q-layout>包裹<q-header>、<q-drawer>、<q-page-container>，页面在<q-page-container>内的<router-view />中切换。Vue 单文件组件（SFC）的语法基础可参考 docs/src/pages/start/ 下的入门章节，布局的完整 API 见 docs/src/pages/layout/。

2.3 css/：全局样式与 Quasar 变量

app.sass（或app.scss/app.css，取决于你选择的 CSS 预处理器）：应用级全局样式入口，在 quasar.config.js 的css数组中注册；
quasar.variables.sass：Quasar 的 Sass 变量文件，可覆盖品牌主色、字体、间距等设计令牌，改动后所有 Quasar 组件样式会随之响应。

Sass/SCSS 的启用与配置方式见 docs/src/pages/quasar-cli-vite/css-preprocessors.md，变量体系说明见 docs/src/pages/style/ 目录下的 Sass/SCSS 变量章节。模板中 Sass 变体（js/sass 增量）与 CSS 变体（js/css 增量）由脚手架按选项生成。

2.4 boot/：你的"main.js"们

boot/目录存放 Boot 文件——应用启动阶段的初始化逻辑。Quasar 的理念是"一个关注点一个 boot 文件"，例如 i18n 初始化（见 i18n 模板）、API 客户端挂载等。每个 boot 文件需在 quasar.config.js 的boot数组中注册（不带扩展名）：

boot: [ 'i18n' ]

新 boot 文件用quasar new boot <name>命令生成。其装配机制见 docs/src/pages/quasar-cli-vite/boot-files.md。从底层看，入口模板 app-vite/templates/entry/app.js 中明确注释：boot 文件就是"你的 main.js"，由构建系统在createAppFn之后、挂载之前按序执行。

2.5 router/：Vue Router 定义与路由表

index.js（或.ts）：创建 Router 实例。模板 js/manualRouting/src/router/index.js 展示了完整的写法——通过defineRouter包装，按import.meta.env.QUASAR_SERVER/QUASAR_VUE_ROUTER_MODE选择 memory / history / hash 三种历史模式，并注释建议"路由模式与 publicPath 应在 quasar.config.js 的build.vueRouterMode、build.publicPath中配置，而不是改这里"；
routes.js（或.ts）：纯路由表，如上文 2.2 所示；
typed-router.d.ts：仅 TypeScript 项目且启用了build.filenameBasedRouting（基于文件名的路由）时自动生成的路由类型文件，为RouterLink、useRoute等提供强类型提示。

两种路由组织方式（手工路由 manualRouting 与基于文件名的 filenameBasedRouting）的完整说明见 docs/src/pages/quasar-cli-vite/page-routing-with-vue-router.md，filenameBasedRouting 的页面组织模板在 js/filenameBasedRouting/src/pages（含index/(index).vue、[...path].vue等约定文件）。

2.6 stores/：Pinia 状态管理

index.js（或.ts）：Pinia 初始化入口。模板 js/pinia/src/stores/index.js 用defineStore包装createPinia()，支持异步创建（SSR 场景需要接收ssrContext），并预留pinia.use(SomePiniaPlugin)插件挂载点；
<store>...：各业务 store 文件，如模板中的example-store.js。

SSR/SSG 模式下 store 会参与"服务端序列化 → 客户端水合"流程，详见 docs/src/pages/quasar-cli-vite/state-management-with-pinia.md。

2.7 App.vue：应用的根组件

src/App.vue是所有页面的根组件，模板中其内容仅含<router-view />（见 js/BASE/src/App.vue）。真正"包含布局"的组件是 layouts/ 下的布局文件，App.vue只负责最外层的路由出口。入口源码 app-vite/templates/entry/app.js 中通过quasarConf.sourceFiles.rootComponent定位该文件并注入 Quasar、Router、Store：

import { Quasar } from 'quasar' import { markRaw } from 'vue' import RootComponent from '@/../<rootComponent 路径>' import createRouter from '@/../<router 路径>' const app = createAppFn(RootComponent) app.use(Quasar, quasarUserOptions) // ... 按需 use store、use router

注意App.vue的路径并非硬编码——它可在 quasar.config.js 的sourceFiles.rootComponent中重新指定（见 js/BASE/quasar.config.js 中的sourceFiles注释块）。

三、src-*/：八个平台模式的专属代码目录

Quasar 支持 SPA 之外的七种目标平台，每种模式会引入一个src-<mode>/目录存放仅在该模式下生效的代码。它们与src/完全隔离，互不干扰：

目录	内容	仓库文档（相对路径）
`src-ssr/`	SSR 专属代码，如生产环境的 Node.js Web 服务器、自定义中间件	docs/src/pages/quasar-cli-vite/developing-ssr/
`src-ssg/`	SSG 专属代码，如 ssg-renderer 脚本	docs/src/pages/quasar-cli-vite/developing-ssg/
`src-pwa/`	PWA 专属代码，如 Service Worker 与 manifest	docs/src/pages/quasar-cli-vite/developing-pwa/
`src-capacitor/`	Capacitor 生成的目录，用于构建移动应用	docs/src/pages/quasar-cli-vite/developing-capacitor-apps/
`src-cordova/`	Cordova 生成的目录，用于构建移动应用	docs/src/pages/quasar-cli-vite/developing-cordova-apps/
`src-electron/`	Electron 专属代码，如主进程（"main" thread）	docs/src/pages/quasar-cli-vite/developing-electron-apps/
`src-bex/`	BEX（浏览器扩展）专属代码，如后台脚本（"main" thread）	docs/src/pages/quasar-cli-vite/developing-browser-extensions/

这些目录由quasar mode add <mode>按需创建。从入口模板 app-vite/templates/entry/app.js 的模板条件块（<% if (quasarConf.ctx.mode.bex) %>、<% if (quasarConf.ctx.mode.capacitor) %>等）可以看出：每种模式不仅在文件层面隔离，还在构建入口层面通过条件渲染注入不同的初始化逻辑（如 BEX 模式先await bex.promise再装配应用，Capacitor 模式注入@capacitor/core与 SplashScreen 隐藏逻辑）。

四、dist/：生产构建的唯一出口

dist/存放所有生产构建产物，按模式分子目录输出：

dist/ ├── spa/ # quasar build（SPA 模式）的输出 ├── ssr/ # SSR 模式：服务器代码 + 客户端资源 ├── electron/ # Electron 模式：打包的应用 └── ... # 其他启用模式

输出目录名可在 quasar.config.js 的build.distDir中调整。这部分产物直接用于部署，不属于源码管理范围（已在.gitignore中忽略）。

五、根目录：从配置到工程规范的七个文件

5.1 quasar.config.js（或 .ts）：一切配置的枢纽

这是 Quasar 应用最重要的配置文件（模板示例），@quasar/app-vite的所有行为都受它驱动，主要包括：

boot：注册 boot 文件数组；
css：全局样式入口；
extras：附加字体/图标库（如roboto-font、material-icons）；
build：Vite 构建相关——target、filenameBasedRouting、vueRouterMode（hash/history）、vueRouterBase、publicPath、extendViteConf、vitePlugins等；
devServer：开发服务器（open自动开浏览器、https等）；
framework：Quasar 框架配置（config、iconSet、lang、plugins）；
animations：引入的动画库；
sourceFiles：重定向各关键源文件路径（rootComponent、router、store、PWA/Electron/BEX 相关文件）；
ssr/ssg/pwa/cordova/capacitor/electron/bex：各模式专属配置块。

完整配置项说明见 docs/src/pages/quasar-cli-vite/quasar-config-file.md，Vite 相关的深度定制见 docs/src/pages/quasar-cli-vite/handling-vite.md。

5.2 index.html：HTML 入口模板

index.html是构建时生成最终 HTML 的模板（Vite 的约定入口）。Quasar 会在其中注入样式、脚本与 meta 标签；PWA 模式下还涉及 manifest 注入（相关配置见pwa.injectPWAMetaTags）。

5.3 工程规范与工具链配置

.gitignore：Git 忽略规则；
.editorconfig：跨编辑器的缩进/换行风格统一（模板）；
eslint.config.js：ESLint 扁平化配置（模板见 js/eslint 增量），配合vite-plugin-checker可在开发时做类型/规范检查（quasar.config.js 中配置示例）；
postcss.config.js：PostCSS 配置；
jsconfig.json：非 TS 项目的编辑器路径别名/智能提示配置（@/*映射）；
tsconfig.json：TS 项目的编译与路径配置；TypeScript 支持细节见 docs/src/pages/quasar-cli-vite/typescript-support.md；
env.d.ts：仅 TS 项目，声明 Vite 环境变量与import.meta.env类型（env.d.ts与typed-router.d.ts一起构成了 TS 模式下的类型底座）。

5.4 package.json 与 README.md

package.json承载 npm 脚本（dev、build、lint等）与依赖声明；README.md是项目/站点的说明文档。Quasar 的dev/build等命令的完整清单见 docs/src/pages/quasar-cli-vite/commands-list.md。

六、源码级印证：目录约定如何被"消费"

目录结构并非摆设，构建系统会按约定从这些路径读取源码。以入口模板 app-vite/templates/entry/app.js 为例，装配顺序清晰展示了各目录的运行时角色：

按quasarConf.sourceFiles.rootComponent定位并导入App.vue（即src/App.vue）；
按sourceFiles.store导入 store（即src/stores/index），hasStore为真时app.use(store)，SSR 下从window.__INITIAL_STATE__水合状态；
按sourceFiles.router导入 router（即src/router/index），并用markRaw包裹后暴露；
返回{ app, store, router }交给上层，由客户端/服务端各自的引导代码决定如何挂载。

Boot 文件则在该模板的注释中明确定位为"your main.js"（app.js 头部注释）：需要初始化逻辑时不要改入口文件，而是quasar new boot <name>新建 boot 文件并在 quasar.config.js 注册。这也解释了为什么目录结构里没有传统 Vite 项目常见的main.js——Quasar 把它"打散"成了boot/+ 约定入口的组合。

七、给初学者的最小关注集

原文给出了非常务实的建议：新手只需关注quasar.config（Quasar 应用配置文件）、src/router、src/layouts、src/pages，以及可选的src/assets。这四个区域覆盖了"配置 → 路由 → 布局 → 页面"的最短开发链路；其余目录（src-*模式目录、dist、各类工具配置）在你真正用到对应能力之前，可以放心忽略。

结语

Quasar CLI with Vite 的目录结构是"约定优先"思想的集中体现：通过固定的目录划分，@quasar/app-vite才能在无需显式配置的情况下自动完成入口装配、模式注入与构建输出。理解这棵目录树，就等于拿到了阅读、维护和扩展任何 Quasar 项目的路线图——无论是只做 SPA 的轻量项目，还是同时开启 SSR、PWA、Electron 与移动端的多平台项目，都能在几分钟内定位到目标文件。