尧图网站设计 尧图网站设计YAOTU DESIGN
ARTICLE DETAIL

资讯详情

深耕网站设计与一线实操的经验洞察。

SvelteKit 页面选项(Page Options)完全指南:prerender、ssr、csr、trailingSlash 与 config 的逐页控制

SvelteKit 页面选项(Page Options)完全指南:prerender、ssr、csr、trailingSlash 与 config 的逐页控制 Web框架后端前端【免费下载链接】kitweb development, streamlined项目地址https://gitcode.com/gh_mirrors/kit/kit点击查看免费下载导读SvelteKit 默认会对每个组件先在服务器端渲染SSR再把生成的 HTML 发送到客户端进行水合hydration最后由客户端路由器接管后续导航。但并非所有页面都适合这种默认处理方式——营销页需要极致速度、动态页需要 SEO 与可访问性、后台管理区可能只需要客户端渲染。本篇文章围绕 documentation/docs/20-core-concepts/40-page-options.md 展开系统讲解prerender、ssr、csr、trailingSlash、config、entries六个页面选项的语义、组合方式与底层实现让你能够按页面粒度自由调配渲染策略。默认渲染流程与选项的作用边界在没有任何配置的情况下SvelteKit 的页面渲染链路是服务器渲染SSR组件先在服务器端渲染为 HTML 并发送给客户端水合hydration客户端再次渲染组件使其可交互路由接管SvelteKit 初始化客户端路由器负责后续导航不再向服务器请求完整页面。这意味着组件必须能够在服务器与浏览器两个环境中运行。而每个页面用哪种策略正是由本篇文章要讲的**页面选项page options**决定的。在哪里导出选项导出位置作用范围page.js/page.server.js单个页面layout.js/layout.server.js一组页面的共享配置根layout.js/layout.server.js整个应用选项的生效遵循子级覆盖父级的规则子布局和页面会覆盖父布局中设定的值。因此你可以在根布局开启全局预渲染再对需要动态渲染的页面单独关闭。也正因为可以混搭SvelteKit 才能支持营销页预渲染 动态页 SSR 管理后台纯 CSRSPA这种高度灵活的应用形态。从源码来看不同模块允许导出的选项集合是严格校验的。在 packages/kit/src/utils/exports.js 中定义layout.js与layout.server.jsload、prerender、csr、ssr、trailingSlash、configpage.js在布局允许的集合上额外增加entriespage.server.js在page.js基础上再增加actionsserver.js仅允许GET/POST等 HTTP 方法处理器、fallback、prerender、trailingSlash、config、entries。任何不在集合内的导出除_前缀的自定义变量外都会在构建时报出类似Invalid export xxx的错误并提示你该选项在哪些文件中是合法的。prerender构建期生成静态 HTML部分路由天然可以用构建期生成的简单 HTML 文件来表示这些路由可以被预渲染prerender。三种取值true构建期把路由生成为静态 HTML 文件/// file: page.js/page.server.js/server.js export const prerender true;false明确标记为不可预渲染。在根layout.js/layout.server.js中设置prerender true即可让全站默认预渲染再对个别页面用false排除/// file: page.js/page.server.js/server.js export const prerender false;auto同时满足预渲染 保留在 SSR 清单中的场景。典型场景是/blog/[slug]这种路由——对最新/最热门内容预渲染长尾内容仍走服务器渲染/// file: page.js/page.server.js/server.js export const prerender auto;预渲染的工作原理标记为prerender true的路由会从动态 SSR 使用的 manifest 中移除使服务器或 serverless/edge 函数的体积更小预渲染器从应用根开始为所有可预渲染页面及server.js路由生成文件每个页面会被扫描其中的a元素凡是链接到其他可预渲染候选页面的都会被继续抓取crawl因此通常无需手动指定访问列表如需手动指定入口可通过config.prerender.entries配置或在动态路由中导出entries函数预渲染过程中从$app/env导入的building值为true。在配置层面config.prerender支持的子项定义于 packages/kit/src/core/config/options.jsconcurrency正整数并发预渲染数默认 1、crawl布尔默认true、entries字符串数组允许*或/开头的绝对路径默认[*]以及handleHttpError、handleMissingId、handleEntryGeneratorMismatch、handleUnseenRoutes、handleInvalidUrl等错误处理策略取值fail、warn、ignore或自定义函数。[!NOTE] 如果整个应用都适合预渲染可直接使用adapter-static它输出的文件可部署到任意静态服务器。预渲染服务器路由prerender与其他页面选项不同它也作用于server.js文件。server.js不受布局影响但会继承从它取数据的页面的默认值。例如下面这个page.js/// file: page.js export const prerender true; /** type {import(./$types).PageLoad} */ export async function load({ fetch }) { const res await fetch(/my-server-route.json); return await res.json(); }那么只要src/routes/my-server-route.json/server.js自身没有export const prerender false它就会被当作可预渲染路由处理。何时不应预渲染基本规则是任何两个直接访问该页面的用户必须从服务器获得相同的内容页面才可预渲染。预渲染内容对所有用户一视同仁。当然你可以在预渲染页面的onMount中通过 fetch 获取个性化数据但这往往带来空白初始内容或加载指示器体验较差基于页面参数加载数据的路由如src/routes/blog/[slug]/page.svelte仍然可以预渲染预渲染期间禁止访问url.searchParams。如需使用请确保只在浏览器端执行例如在onMount中包含 actions 的页面不能预渲染因为服务器必须能够处理 action 的POST请求。路由冲突由于预渲染要写入文件系统目录与文件不能同名。例如src/routes/foo/server.js和src/routes/foo/bar/server.js会尝试生成foo与foo/bar这是不可能的。因此建议始终为端点endpoint添加文件扩展名src/routes/foo.json/server.js与src/routes/foo/bar.json/server.js会分别生成foo.json与foo/bar.json和谐共存。对于页面SvelteKit 通过写入foo/index.html而不是foo来绕开这一问题。故障排查若出现The following routes were marked as prerenderable, but were not prerendered错误说明该路由或其父布局设置了prerender true但预渲染爬虫没有到达它因而未生成文件。由于这类路由无法动态 SSR访问时必然报错。解决办法通过config.prerender.entries或页面的entries选项让 SvelteKit 能找到该路由——尤其是带[参数]的动态路由爬虫不知道参数应取何值必须显式列出未标记为可预渲染的页面会被忽略其链接也不会被爬取确保可以从某个开启了服务器端渲染的已预渲染页面中发现指向该路由的链接将export const prerender true改为export const prerender autoauto路由可以退化为动态服务器渲染。entries为动态路由声明预渲染入口SvelteKit 默认从**入口点entry points**开始自动发现并爬取要预渲染的页面所有非动态路由默认都是入口点。例如/ # 非动态 /blog # 非动态 /blog/[slug] # 动态因为有 [slug]SvelteKit 会预渲染/和/blog并在过程中发现a href/blog/hello-world这样的链接从而得到新的可预渲染页面。大多数情况下这已经足够。但某些时候指向/blog/hello-world的链接不存在或不存在于已预渲染页面上此时就需要显式告知 SvelteKit。可以用config.prerender.entries也可以在动态路由的page.js、page.server.js或server.js中导出entries函数/// file: src/routes/blog/[slug]/page.server.js /** type {import(./$types).EntryGenerator} */ export function entries() { return [ { slug: hello-world }, { slug: another-blog-post } ]; } export const prerender true;entries可以声明为async函数例如从 CMS 或数据库拉取文章列表后返回——这使其成为内容型站点博客、文档站预渲染的标配做法。ssr关闭服务器端渲染正常情况下 SvelteKit 先在服务器渲染页面 HTML 再发送给客户端进行水合这也是预渲染保存完整页面内容的前提。将ssr设为false时服务器只渲染一个空外壳shell页面。这在页面无法在服务器渲染例如使用了document这类仅浏览器可用的全局对象时很有用但大多数场景并不推荐/// file: page.js export const ssr false; // 如果 ssr 和 csr 同时为 false将什么都不渲染在根layout.js中设置export const ssr false整个应用将只在客户端渲染——这实际上把应用变成了 SPA。注意如果目标是构建静态站点SSG不应这样做。[!NOTE] 静态求值与动态求值如果所有页面选项都是布尔值或字符串字面量SvelteKit 会在构建期静态求值否则它会在服务器导入page.js或layout.js来求值选项构建期执行应用非全静态时运行期也会执行。第二种情况下模块被加载时绝不能执行仅浏览器可用的代码——实际使用中应把浏览器专用代码放在page.svelte或layout.svelte中导入。csr关闭客户端渲染与水合通常 SvelteKit 会把服务器渲染的 HTML 水合成可交互的客户端渲染CSR页面。但很多页面根本不需要 JavaScript——大量博客文章和关于页面就属于这一类/// file: page.js export const csr false; // 如果 csr 和 ssr 同时为 false将什么都不渲染关闭 CSR 意味着不向客户端发送任何 JavaScript具体影响网页应仅依赖 HTML 与 CSS 工作所有 Svelte 组件内部的script标签会被移除form元素无法使用渐进增强链接由浏览器以整页导航方式处理热模块替换HMR会被禁用。开发阶段若想保留 HMR 等能力可以这样写/// file: page.js import { dev } from $app/env; export const csr dev;这样开发环境下csr为true开启水合与 HMR生产构建为false。trailingSlash控制 URL 尾部斜杠默认情况下 SvelteKit 会移除URL 尾部的斜杠——访问/about/会得到一次重定向到/about。trailingSlash选项可以改变这一行为取值有三种取值行为never默认移除尾部斜杠/about/重定向到/aboutalways保留/补充尾部斜杠ignore不重定向/about与/about/都正常响应与其它页面选项一样可以从layout.js/layout.server.js导出以作用于所有子页面也可以在server.js中导出/// file: src/routes/layout.js export const trailingSlash always;该选项同样影响预渲染trailingSlash为always时/about会生成about/index.html否则生成about.html与静态服务器的惯例保持一致。[!NOTE] 不推荐ignore两种情况下的相对路径语义不同从/x出发的./y是/y而从/x/出发则是/x/y且/x与/x/会被搜索引擎视为两个独立 URL对 SEO 有害。config按平台细化部署参数借助 adapters 的概念SvelteKit 可以运行在多种平台上而每个平台可能都有特定的部署配置——例如在 Vercel 上你可能想把部分应用部署到 edge其余部署到 serverless。config是一个顶层键值对对象具体结构取决于你使用的 adapter每个 adapter 都应提供可导入的Config类型以保证类型安全。配合 JSDoc 或 TypeScript 使用/// file: src/routes/page.js /** type {import(some-adapter).Config} */ export const config { runtime: edge };config对象在顶层进行合并更深层级不合并。这意味着如果只想覆盖上层layout.js的部分值不必在page.js中重复全部内容。例如以下布局配置/// file: src/routes/layout.js export const config { runtime: edge, regions: all, foo: { bar: true } }被这个页面配置覆盖/// file: src/routes/page.js export const config { regions: [us1, us2], foo: { baz: true } }最终该页面得到的配置值为{ runtime: edge, regions: [us1, us2], foo: { baz: true } }——顶层键按页面值覆盖regions未提及的键继承布局值runtime而foo作为深层级对象被整体替换不会逐字段合并。组合策略一个可落地的整体方案把以上选项组合起来可以构建典型的混合渲染架构营销页/落地页prerender truecsr false构建期生成纯静态 HTML速度最快动态内容页博客文章、产品详情保持默认 SSR必要时对热门内容用prerender auto兼顾 SEO 与可访问性后台管理区在管理区布局中ssr false使其退化为纯客户端 SPA避免服务器渲染管理界面中的浏览器专用逻辑带 actions 的交互页面保持ssr true、csr true依赖服务器处理表单提交。对应验证代码可在仓库测试应用中找到大量实例例如packages/kit/test/apps/basics/src/routes/no-csr/page.jscsr false的端到端用例、packages/kit/test/apps/basics/src/routes/no-ssr/layout.js整站关闭 SSR 的用例以及packages/kit/test/apps/basics/src/routes/routing/trailing-slash/layout.jstrailingSlash的路径行为用例。结语页面选项是 SvelteKit 渲染架构的核心控制面prerender决定构建期是否生成静态文件true/false/auto三态ssr与csr分别控制服务端与客户端渲染entries为动态路由声明预渲染入口trailingSlash管理 URL 语义config则打通了与各类部署平台的定制通道。它们都遵循子级覆盖父级的继承模型让开发者可以按页面粒度精确调配渲染策略构造出预渲染、SSR 与 SPA 共存的混合应用。赞分享Web框架后端前端【免费下载链接】kitweb development, streamlined项目地址https://gitcode.com/gh_mirrors/kit/kit点击查看免费下载相关推荐Angular 渲染策略完全指南为不同页面选择 CSR、SSG 与 SSRAngular 渲染策略完全指南为不同页面选择 CSR、SSG 与 SSR 导读 本篇指南以 rendering strategies.md https://前端Web框架Dompdf页面布局完全指南page规则与CSS分页控制Dompdf页面布局完全指南page规则与CSS分页控制 在文档转换过程中精确的页面布局控制往往是开发者最头疼的问题。你是否曾因PDF分页混乱、页眉页脚错后端Hugo 列表页List Page完全指南页面集合、模板选择与分页实战Hugo 列表页List Page完全指南页面集合、模板选择与分页实战 列表页list page是 Hugo 站点中负责聚合展示的一类页面它接收开发工具前端CLI上一篇Skia离屏渲染技术Surface创建与DeferredDisplayList应用下一篇跨平台容器瘦身SLIM多系统安装与使用指南创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表