Quasar SSG 模式下的 TypeScript 使用指南ssg-renderer.ts 与类型安全的页面生成【免费下载链接】quasarQuasar Framework - Build high-performance VueJS user interfaces in record time项目地址: https://gitcode.com/gh_mirrors/qu/quasar本指南基于 quasar/app-vite 的 SSG静态站点生成模式讲解如何在 TypeScript 项目中使用/src-ssg/ssg-renderer.ts定义待渲染页面并借助defineSsgGetPages、defineSsgRenderPreloadTag等 wrapper 获得完整的类型推断与智能提示。读完本文你将掌握 SSG 渲染器的 TypeScript 写法、路由解析辅助函数的使用、renderer 专属依赖的隔离安装方式以及从 JS 项目平滑迁移到 TS 的具体步骤。SSG 模式与 TypeScript 的自动集成在 Quasarquasar/app-vite中当为TypeScript 项目添加 SSG 模式时Quasar 会在/src-ssg目录下自动创建ssg-renderer.ts文件。如果你是在已有的 JavaScript 项目中启用 SSG只需手动将ssg-renderer.js重命名为ssg-renderer.ts即可——Quasar 对这两种扩展名都能自动发现无需额外配置。从仓库模板可以印证这一点app-vite/templates/ssg 目录下同时维护了js/ssg-renderer.js与ts/ssg-renderer.ts两套模板脚手架会根据项目的语言选型生成对应文件。Beta 阶段警告Quasar SSG 模式目前处于beta 阶段。API 可能根据社区反馈在未来发生变化每次升级quasar/app-vite时请务必查看 release notes。Wrapper 函数类型推断从导入开始SSG 渲染器中的两个核心导出都通过#q-app提供的 wrapper 函数定义wrapper 会自动推断回调参数与返回值的类型defineSsgGetPages—— 包装页面获取回调defineSsgRenderPreloadTag—— 包装预加载标签渲染回调。这两个 wrapper 在 app-vite/exports/wrappers.js 中导出是#q-app别名暴露给应用侧的类型安全入口。由于类型信息来自 app-vite/types/app-wrappers.d.ts在 TS 项目中编写回调时编辑器会给出完整的参数提示如parseVueRouterRoutes、ctx、quasarConfSsg等返回值也会被严格约束为SsgPage[]。编写 ssg-renderer.ts完整示例以下是 TypeScript 项目中ssg-renderer.ts的典型写法与 模板文件 保持一致import { defineSsgGetPages, defineSsgRenderPreloadTag } from #q-app import routes from /router/routes export const getSsgPages defineSsgGetPages( async ({ parseVueRouterRoutes }) { // parseVueRouterRoutes 是可选的辅助函数 const { ssgPages } await parseVueRouterRoutes({ routes, verbose: true }) return ssgPages } ) const jsRE /\.js$/ const cssRE /\.css$/ const woffRE /\.woff$/ const woff2RE /\.woff2$/ const gifRE /\.gif$/ const jpgRE /\.jpe?g$/ const pngRE /\.png$/ export const renderPreloadTag defineSsgRenderPreloadTag( (file /* , { ssrContext } */) { if (jsRE.test(file)) { return link relmodulepreload href${file} crossorigin } if (cssRE.test(file)) { return link relstylesheet href${file} crossorigin } if (woffRE.test(file)) { return link relpreload href${file} asfont typefont/woff crossorigin } if (woff2RE.test(file)) { return link relpreload href${file} asfont typefont/woff2 crossorigin } if (gifRE.test(file)) { return link relpreload href${file} asimage typeimage/gif crossorigin } if (jpgRE.test(file)) { return link relpreload href${file} asimage typeimage/jpeg crossorigin } if (pngRE.test(file)) { return link relpreload href${file} asimage typeimage/png crossorigin } return // 不需要预加载时返回空字符串 } )注意SSG 渲染器只在quasar build -m ssg时运行。开发模式按需渲染请求的路由不会调用getSsgPages()。详见 SSG Renderer。使用 filenameBasedRouting 时的写法当在/quasar.config中启用了build filenameBasedRouting时路由由 Vue Router 基于文件结构自动生成此时应改用getFilenameBasedRoutes()辅助函数获取路由import { defineSsgGetPages } from #q-app export const getSsgPages defineSsgGetPages( async ({ getFilenameBasedRoutes, parseVueRouterRoutes }) { const routes await getFilenameBasedRoutes() const { ssgPages } await parseVueRouterRoutes({ routes, verbose: true }) return ssgPages } )parseVueRouterRoutes从 Vue Router 路由到 SSG 页面parseVueRouterRoutes是内置的异步辅助函数用于解析 Vue Router 路由配置并自动生成待渲染页面列表。它会忽略重定向redirects、带动态参数params的路由以及标记为 CSR客户端渲染的路由——这些路由如需生成页面需要手动补充定义。其完整签名与参数说明可在 ssg-renderer.md 的SsgParseVueRouterParams类型中找到核心参数如下参数类型默认值说明routesRouteRecordRaw[]必填要解析的 Vue Router 路由定义parentPathstring/用于这些路由的父路径crawlIgnoreRoutesstring[][]picomatch 模式列表匹配的路由被忽略但仍会遍历其子路由routesDynamicParamsMapRecordstring, ...{}动态路由段的参数值映射verbosebooleanfalse是否输出详细日志为true时记录被忽略的动态参数路由crawlIgnoreRoutes的 picomatch 模式示例/admin—— 仅匹配该确切路由/admin/**—— 匹配该路由及其全部子路由/admin/*—— 仅匹配/admin的直接子路由/admin/{users,settings}—— 同时匹配/admin/users与/admin/settings。routesDynamicParamsMap支持全部 vue-router 参数语法语义与router.resolve()一致可选参数如/user/:id?省略参数键或用空字符串作为值来去掉该段例如{ /user/:id?: [{}] }或{ /user/:id?: [{ id: }] }会为/user生成页面可重复参数如/chapters/:chapter用数组填充重复段{ /chapters/:chapter: [{ chapter: [one, two] }] }生成/chapters/one/two自定义正则参数如/items/:id(\\d)值直接替换而不校验正则与router.resolve()行为一致示例{ /user/:id: [{ id: 1 }, { id: 2 }] }会为/user/1与/user/2生成页面。parseVueRouterRoutes返回SsgParseVueRouterResult包含ssgPages生成的页面列表、hasIgnoredRoutes是否有被忽略的路由以及crawlIgnoredSsgPages、ignoredDynamicParamSsgPages、ignoredCsrSsgPages三组被忽略路由的明细便于在verbose: true时排查问题。SsgPage 类型每个页面的可选配置defineSsgGetPages的返回值是SsgPage[]其中每个页面对象SsgPage支持以下属性属性类型默认值说明routestring必填要渲染的 vue-router 路由必须是路由配置中的有效路由vueRouterRouteRouteRecordRaw—原始 Vue Router 路由对象labelstring—日志中用于标识该页面的标签dirstring由路由推断生成 HTML 文件的目标目录相对 dist 目录的路径会与build distDir拼接拒绝绝对路径、父级穿越与符号链接逃逸filenamestringindex.html生成的 HTML 文件名同样受 dist 目录约束ssrContextSsgPageSsrContext默认 SSR context渲染该页面时使用的 SSR 上下文会合并进ssrContext其中req为node:http的IncomingMessage原生类型transformHtml(html) string \| Promisestring \| void—页面渲染后、写入磁盘前对 HTML 的回调钩子返回字符串会替换生成内容例如从数据文件动态生成页面import { defineSsgGetPages } from #q-app import products from /data/products.json export const getSsgPages defineSsgGetPages(() [ { route: / }, ...products.map(product ({ route: /products/${product.slug}, label: product.name })) ])警告定义route时不要包含quasar.config build.publicPath请将其视为纯 Vue Router 路由。关于 404 页面的注意事项应用中通常会有 Vue Router 的 catch-all 路由{ path: /:catchAll(.*)*, component: () import(/pages/Error404.vue) }如果某个页面定义包含不存在的路由Vue Router 会将其解析到 catch-allQuasar 会写入渲染出的 404 标记。由于这是合法渲染构建过程无法推断路由是笔误。Quasar 会单独生成配置的 SSG 404 Error Page因此不要为默认的404.html添加页面定义。管理 renderer 专属依赖/src-ssg/package.jsonSSG 渲染器使用独立的 Rolldown 配置构建可通过ssg.extendSSGRendererConf扩展因此只被/src-ssg/ssg-renderer直接导入的依赖应声明在/src-ssg/package.json中与应用的根package.json隔离。生成的模板文件见 app-vite/templates/ssg/common/package.json{ name: quasar-ssg-app, version: 1.0.0, description: Quasar SSG folder, type: module, private: true, dependencies: {} }例如在渲染器中使用tinyglobby扫描 Markdown 文件就应在/src-ssg目录下安装# 在 /src-ssg 目录下执行 pnpm add tinyglobby # PNPM yarn add tinyglobby # Yarn npm install tinyglobby # NPM bun add tinyglobby # Bun警告被/src下的应用代码导入的包仍然属于根package.json。只有 renderer 专属的包才安装到/src-ssg下。详见 Installing SSG-specific dependencies。缺失类型声明的处理如果某个依赖本身不包含类型声明没有types字段或types归属请将对应的types/*包安装到/src-ssg/package.json的devDependencies中。这样既保证 TypeScript 编译期有完整的类型信息又不会把类型包混入运行期依赖。从 JS 项目迁移到 TS 的检查清单将ssg-renderer.js重命名为ssg-renderer.tsTypeScript 新项目由脚手架自动生成确认文件从#q-app导入defineSsgGetPages与defineSsgRenderPreloadTag替换原有的裸导出依赖parseVueRouterRoutes时核对参数类型routes、parentPath、crawlIgnoreRoutes、routesDynamicParamsMap、verbose若 renderer 引入了额外包将其加入/src-ssg/package.json并在该目录安装缺少声明时补充对应types/*到 devDependencies运行quasar build -m ssg验证类型检查与页面生成或参照 Configuring SSG 调整ssg配置项如error404HtmlFilename、clientSideRenderingRoutes、ssgRendererConcurrency等。延伸阅读SSG Renderer 完整 API 与页面示例配置 SSGquasar.config 的 ssg 选项SSG 专属依赖安装SSG 代码注意事项通用代码约束SSG PWA 组合混合 SSG 部分 CSR【免费下载链接】quasarQuasar Framework - Build high-performance VueJS user interfaces in record time项目地址: https://gitcode.com/gh_mirrors/qu/quasar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
