Quasar Appquasar/app-vite资源处理完全指南src/assets 与 public 目录的边界与实战【免费下载链接】quasarQuasar Framework - Build high-performance VueJS user interfaces in record time项目地址: https://gitcode.com/gh_mirrors/qu/quasar导读本文围绕 Quasar Framework 的 Vite 构建方案quasar/app-vite讲解应用资源Assets的标准处理方式核心解决一个每个 Quasar 开发者都会遇到的问题public/与src/assets/两个目录到底有什么区别、什么资源该放哪里、在模板和 CSS 中如何正确引用。读完本文你将掌握 Vite 资源解析规则相对路径、~前缀、别名、import.meta.env.BASE_URL的正确用法、publicPath与部署子路径的关系以及 SPA/PWA/SSR/SSG/Electron/Cordova 等不同模式下资源处理的差异可以直接应用到实际项目中。两个目录/public与/src/assets打开任意一个 Quasar 项目你会发现项目结构中存在两个与资源相关的目录/public静态资源目录/src/assets常规资源目录。两者的核心区别在于静态资源会被原样复制到构建产物目录而常规资源会被构建系统处理内联、复制、重命名并嵌入。前者原封不动后者参与构建。从源码层面看Quasar 通过 app-vite/lib/utils/get-app-paths.js 定义了完整的应用路径体系其中publicDir resolve(appDir, public)第 52 行即public/目录的绝对路径srcDir resolve(appDir, src)第 53 行即源码目录。随后在 app-vite/lib/config-tools.js 构建 Vite 配置时这两个目录被分别映射到 Vite 的base与publicDir配置项const viteConf { root: appPaths.appDir, base: build.publicPath, publicDir: build.ignorePublicFolder ? false : appPaths.publicDir, // ... }也就是说src/assets本质上是普通源码文件交给 Vite 的模块系统处理而public目录被显式指定为 Vite 的publicDir走的是原样拷贝通道。理解这一映射就理解了整个资源体系的底层逻辑。常规资源/src/assets与 Vite 的解析规则在*.vue组件中模板和 CSS 都会被 Vite 解析以查找资源 URL。例如img src./logo.pngbackground: url(./logo.png)这里的./logo.png是一个相对资源路径Vite 会把它当作模块依赖来解析。由于这些资源在构建过程中可能被内联inline、复制copy、重命名rename它们本质上是源代码的一部分。这正是官方推荐将 Vite 处理的资源放在/src/assets下、与其它源码文件为伴的原因。[!TIP] 实际上你并不一定非要把所有资源都放进/src/assets。完全可以按照使用它们的模块/组件来组织目录结构。例如将每个组件放在自己的目录中把它的静态资源就放在组件旁边。资源解析规则详解规则一相对 URL 会被当作模块依赖形如./assets/logo.png的相对路径会被解释为模块依赖构建时会被替换为基于 Vite 输出配置即build publicPath自动生成的 URL。规则二~前缀触发模块解析以~开头的 URL 会被当作模块请求处理等价于import some-module/image.png。当你希望利用 Vite 的模块解析配置比如别名时必须使用这个前缀。Quasar 开箱即用地提供了assets别名官方推荐的用法是img src~/assets/logo.png注意~位于/assets之前。这个别名并非魔法而是 Quasar 在 app-vite/lib/quasar-config-file.js 中显式注册的框架默认别名const defaultAliases { : appPaths.srcDir, // 指向项目的 src/ 目录 #q-app: quasar/app-vite // 指向 CLI 自身 } for (const aliasKey in defaultAliases) { if (!(aliasKey in alias)) { alias[aliasKey] defaultAliases[aliasKey] } }注意其中用户自定义别名优先于框架默认值的规则如果你在build.alias中自行定义了则以你的配置为准框架默认别名只在用户未定义时才注入。这些别名会被进一步合并进 Vite 的resolve.alias见 app-vite/lib/config-tools.js同时同步到生成的.quasar/tsconfig.json的paths中见 app-vite/lib/types-generator.js 附近因此 TypeScript 项目中的/assets/...导入也能获得正确的类型提示与路径解析。所以在 Vue 模板中~/前缀 /别名组合~/assets/...是引用src/assets下资源的最规范方式在script中也可以直接使用import logo from ~/assets/logo.png或import logo from /assets/logo.png的方式导入资源模块。静态资源/public与根相对 URL需要保持原始文件名和路径不变的文件例如 favicon、robots.txt、URL 由数据动态拼接而来的图片应该放在public/目录中。public/目录的内容会被原样复制到构建产物dist目录不做任何处理。引用它们时应使用根相对 URL例如img src/logo.png这类 URL完全不会被处理浏览器从域名根路径去解析它们因此只有当build publicPath为/默认值时它们才与public/目录对应。当应用部署在子路径下时需要加上import.meta.env.BASE_URL前缀——Vite 会把这个值设置为你的publicPathtemplate img :srcbase logo.png / /template script setup const base import.meta.env.BASE_URL /scriptpublicPath 的底层处理import.meta.env.BASE_URL的值并非随意生成而是来自 Quasar 对build publicPath的规范化处理。在 app-vite/lib/quasar-config-file.js 中formatPublicPath()会执行以下规范化export function formatPublicPath(publicPath) { if (!publicPath) return / if (!publicPath.endsWith(/)) { publicPath ${publicPath}/ } if (publicPath relativePublicPath || urlRegex.test(publicPath)) { return publicPath } if (!publicPath.startsWith(/)) { publicPath /${publicPath} } return publicPath }即空值默认/缺少尾部斜杠时自动补上不以/开头时自动补上。最终这个规范化后的publicPath会作为 Vite 的base配置app-vite/lib/config-tools.js并注入 HTML 模板中见 app-vite/lib/plugins/vite.html.js 的injectPublicPath()。此外Quasar 还支持相对形式的publicPath./见 app-vite/lib/quasar-config-file.js但存在严格限制getRelativePublicPathError()第 138-153 行仅 SPA 和 PWA 模式支持相对 publicPath使用相对 publicPath 时vueRouterMode必须为hashCapacitor、Cordova、Electron、BEX 等混合模式不支持。部署在子路径时务必同时保证build publicPath与build vueRouter的路由 base 一致formatRouterBase()第 166-176 行会从 publicPath 推导路由 base否则会出现资源能加载但路由跳转 404 的问题。关于public资源的警告与提醒[!WARNING] 裸相对 URL如logo.png没有前导斜杠同样不会被处理。浏览器会基于当前页面 URL 解析它一旦路由超过一个段位就会出错例如/users/42页面会去请求/users/logo.png。引用 public 资源时永远使用前导/或import.meta.env.BASE_URL前缀。[!TIP]Assets vs Statics常规资源 vs 静态资源src/assets中的文件只有当它们被某个 Vue 文件中以字面量引用时才会被纳入构建public/中的每个文件和文件夹无论是否被引用都会被原样复制进生产构建产物。[!CAUTION] 当构建的不是 SPA/PWA/SSR/SSG 时例如 Electron 或 Cordova 应用/public/icons/*和/public/favicon.ico不会被嵌入应用中因为对这些模式它们没有意义。Electron、Cordova 这类应用并不需要这些 Web 资源。这一行为的直接原因是 Quasar 在 app-vite/lib/utils/get-app-paths.js 与 app-vite/lib/config-tools.js 中按模式驱动 Vite 配置publicDir是否启用、以及各模式如何消费public目录取决于当前激活的构建模式。非 Web 模式Electron、Cordova、Capacitor、BEX会把构建产物交给各自的打包器处理public中的浏览器专用文件自然被排除在外。生产构建中的表现差异从构建结果层面可以更直观地理解两者的区别src/assets中的资源构建后出现在 dist 的assets/目录下对应 Vite 的build.assetsDir默认值为assets见 app-vite/lib/plugins/vite.strip-filename-hashes.js文件名会带内容哈希、可能被压缩或内联且引用 URL 会根据publicPath自动生成。Quasar 的构建产物汇总逻辑app-vite/lib/utils/print-build-summary.js也会统计这些产物。public/中的资源原封不动地出现在 dist 根目录文件名、目录结构、内容一律不变。这也解释了为什么要慎重选择放置位置场景推荐目录引用方式组件/页面私有图片、构建期要处理的资源src/assetsimg src~/assets/xxx.png或 CSSurl()保持文件名不变的 favicon、robots.txtpublicimg src/xxx.pngURL 来自后端数据、运行时动态拼接publicimport.meta.env.BASE_URL 文件名需要模块解析、别名、哈希指纹src/assets模块导入或~前缀与 Vite 官方指南的关系本文所述规则与 Vite 官方资源处理指南 一脉相承Quasar 的quasar/app-vite在 Vite 之上做了一层薄封装将publicPath映射为 Vite 的base、将public/映射为 Vite 的publicDir、注入与#q-app别名其余解析行为相对路径、~前缀、import.meta.env.BASE_URL、资源内联阈值等均遵循 Vite 的标准语义。因此深入阅读 Vite 官方文档可以进一步了解资源内联阈值build.assetsInlineLimit、SVG 处理、new URL()动态导入等进阶话题。总结src/assets是参与构建的源码资源推荐用~/assets/...~触发模块解析、是 Quasar 默认别名指向src/引用适合组件私有、需要哈希指纹或内联的资源public是原样拷贝的静态资源用/根相对 URL 或import.meta.env.BASE_URL引用适合 favicon、robots.txt、动态拼接 URL 的图片build publicPath决定部署子路径下的资源基准路径Quasar 会对其进行规范化并同步到 Vitebase与 Vue Router base非 Web 模式Electron/Cordova 等下public/icons/*与favicon.ico不会被嵌入。掌握以上规则即可在 Quasar 项目中游刃有余地组织资源避免部署后图片 404、子路径加载失败等常见问题。【免费下载链接】quasarQuasar Framework - Build high-performance VueJS user interfaces in record time项目地址: https://gitcode.com/gh_mirrors/qu/quasar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考