SvelteKit 最新中文文档教程（10）—— 部署 Cloudflare Pages 和 Cloudflare Workers
<h2 id="前言">前言</h2><p>Svelte，一个语法简洁、入门容易，面向未来的前端框架。</p>
<p>从 Svelte 诞生之初，就备受开发者的喜爱，根据统计，<strong>从 2019 年到 2024 年，连续 6 年一直是开发者最感兴趣的前端框架 No.1</strong>：</p>
<p><img src="https://yayujs-blog.oss-cn-beijing.aliyuncs.com/405488775-48df16b1-939c-489b-8d52-6071869893f0.png"></p>
<p>Svelte 以其独特的编译时优化机制著称，具有<strong>轻量级</strong>、<strong>高性能</strong>、<strong>易上手</strong>等特性，<strong>非常适合构建轻量级 Web 项目</strong>。</p>
<p>为了帮助大家学习 Svelte，我同时搭建了 Svelte 最新的中文文档站点。</p>
<p>如果需要进阶学习，也可以入手我的小册《Svelte 开发指南》，语法篇、实战篇、原理篇三大篇章带你系统掌握 Svelte！</p>
<p>欢迎围观我的“网页版朋友圈”、加入“冴羽·成长陪伴社群”，踏上“前端大佬成长之路”。</p>
<h2 id="cloudflare-pages">Cloudflare Pages</h2>
<p>要部署到 Cloudflare Pages，请使用 <code>adapter-cloudflare</code>。</p>
<p>当您使用 <code>adapter-auto</code> 时，此适配器将被默认安装。如果您计划继续使用 Cloudflare Pages，您可以从 <code>adapter-auto</code> 切换到直接使用这个适配器，这样在本地开发时可以模拟 Cloudflare Workers 特定的值，类型声明会自动应用，并且提供设置 Cloudflare 特定选项的功能。</p>
<h3 id="比较">比较</h3>
<ul>
<li><code>adapter-cloudflare</code> – 支持所有 SvelteKit 功能；为 Cloudflare Pages 构建</li>
<li><code>adapter-cloudflare-workers</code> – 支持所有 SvelteKit 功能；为 Cloudflare Workers 构建</li>
<li><code>adapter-static</code> – 仅生成客户端静态资源；兼容 Cloudflare Pages</li>
</ul>
<h3 id="使用方法">使用方法</h3>
<p>使用 <code>npm i -D @sveltejs/adapter-cloudflare</code> 安装，然后将适配器添加到您的 <code>svelte.config.js</code> 中：</p>
<pre><code class="language-js">// @errors: 2307
/// file: svelte.config.js
import adapter from '@sveltejs/adapter-cloudflare';
export default {
kit: {
adapter: adapter({
// 以下选项的说明请见下文
routes: {
include: ['/*'],
exclude: ['<all>']
},
platformProxy: {
configPath: 'wrangler.toml',
environment: undefined,
experimentalJsonConfig: false,
persist: false
}
})
}
};
</code></pre>
<h3 id="选项">选项</h3>
<h4 id="routes">routes</h4>
<p>允许您自定义由 <code>adapter-cloudflare</code> 生成的 <code>_routes.json</code> 文件。</p>
<ul>
<li><code>include</code> 定义将调用函数的路由，默认为 <code>['/*']</code></li>
<li><code>exclude</code> 定义将<em>不</em>调用函数的路由 — 这是一种更快且更经济的方式来提供应用的静态资源。这个数组可以包含以下特殊值：
<ul>
<li><code><build></code> 包含您的应用构建产物（由 Vite 生成的文件）</li>
<li><code><files></code> 包含您的 <code>static</code> 目录的内容</li>
<li><code><prerendered></code> 包含预渲染页面的列表</li>
<li><code><all></code> (默认值) 包含以上所有内容</li>
</ul>
</li>
</ul>
<p>您可以组合使用最多 100 个 <code>include</code> 和 <code>exclude</code> 规则。通常您可以省略 <code>routes</code> 选项，但如果（例如）您的 <code><prerendered></code> 路径超过了该限制，您可能会发现手动创建一个包含 <code>'/articles/*'</code> 的 <code>exclude</code> 列表比自动生成的 <code>['/articles/foo', '/articles/bar', '/articles/baz', ...]</code> 更有帮助。</p>
<h4 id="platformproxy">platformProxy</h4>
<p>模拟 <code>platform.env</code> 本地绑定的偏好设置。完整的选项列表请参见 getPlatformProxy Wrangler API 文档。</p>
<h3 id="部署">部署</h3>
<p>请按照 Cloudflare Pages 的入门指南开始。</p>
<p>配置项目设置时，您必须使用以下设置：</p>
<ul>
<li><strong>框架预设</strong> – SvelteKit</li>
<li><strong>构建命令</strong> – <code>npm run build</code> 或 <code>vite build</code></li>
<li><strong>构建输出目录</strong> – <code>.svelte-kit/cloudflare</code></li>
</ul>
<h3 id="运行时-api">运行时 API</h3>
<p><code>env</code> 对象包含您项目的绑定，包括 KV/DO 命名空间等。它通过 <code>platform</code> 属性传递给 SvelteKit，同时还有 <code>context</code>、<code>caches</code> 和 <code>cf</code>，这意味着您可以在 hooks 和端点中访问它：</p>
<pre><code class="language-js">// @errors: 7031
export async function POST({ request, platform }) {
const x = platform.env.YOUR_DURABLE_OBJECT_NAMESPACE.idFromName('x');
}
</code></pre>
<blockquote>
<p>[!NOTE] 应优先使用 SvelteKit 内置的 <code>$env</code> 模块来处理环境变量。</p>
</blockquote>
<p>要为您的绑定包含类型声明，请在您的 <code>src/app.d.ts</code> 中引用它们：</p>
<pre><code class="language-ts">/// file: src/app.d.ts
import { KVNamespace, DurableObjectNamespace } from '@cloudflare/workers-types';
declare global {
namespace App {
interface Platform {
+++ env?: {
YOUR_KV_NAMESPACE: KVNamespace;
YOUR_DURABLE_OBJECT_NAMESPACE: DurableObjectNamespace;
};+++
}
}
}
export {};
</code></pre>
<h4 id="本地测试">本地测试</h4>
<p>在开发和预览模式下会模拟 <code>platform</code> 属性中的 Cloudflare Workers 特定值。本地绑定是基于您的 <code>wrangler.toml</code> 文件中的配置创建的，并在开发和预览期间用于填充 <code>platform.env</code>。使用适配器配置中的 <code>platformProxy</code> 选项 来更改您的绑定偏好设置。</p>
<p>要测试构建，您应该使用 wrangler <strong>版本 3</strong>。构建完网站后，运行 <code>wrangler pages dev .svelte-kit/cloudflare</code>。</p>
<h3 id="注意事项">注意事项</h3>
<p>项目根目录中的 <code>/functions</code> 目录中的函数将<em>不会</em>包含在部署中，这些函数会被编译到一个单一的 <code>_worker.js</code> 文件中。函数应该作为 服务端点 在您的 SvelteKit 应用中实现。</p>
<p>特定于 Cloudflare Pages 的 <code>_headers</code> 和 <code>_redirects</code> 文件可以通过将它们放入 <code>/static</code> 文件夹来用于静态资源响应（如图片）。</p>
<p>然而，它们对 SvelteKit 动态渲染的响应没有影响，这些响应应该从 服务端点 或通过 <code>handle</code> 钩子返回自定义头部或重定向响应。</p>
<h3 id="故障排除">故障排除</h3>
<h4 id="进一步阅读">进一步阅读</h4>
<p>您可能想参考 Cloudflare 关于部署 SvelteKit 站点的文档。</p>
<h4 id="访问文件系统">访问文件系统</h4>
<p>您不能在 Cloudflare Workers 中使用 <code>fs</code> — 您必须预渲染相关路由。</p>
<h2 id="cloudflare-workers">Cloudflare Workers</h2>
<p>要部署到 Cloudflare Workers，请使用 <code>adapter-cloudflare-workers</code>。</p>
<blockquote>
<p>[!NOTE] 除非您有特别原因使用 <code>adapter-cloudflare-workers</code>，否则建议使用 <code>adapter-cloudflare</code>。两个适配器具有相同的功能，但 Cloudflare Pages 提供了更多功能，如 GitHub 集成自动构建和部署、预览部署、即时回滚等。</p>
</blockquote>
<h3 id="使用方法-1">使用方法</h3>
<p>使用 <code>npm i -D @sveltejs/adapter-cloudflare-workers</code> 安装，然后将适配器添加到您的 <code>svelte.config.js</code> 中：</p>
<pre><code class="language-js">// @errors: 2307
/// file: svelte.config.js
import adapter from '@sveltejs/adapter-cloudflare-workers';
export default {
kit: {
adapter: adapter({
config: 'wrangler.toml',
platformProxy: {
configPath: 'wrangler.toml',
environment: undefined,
experimentalJsonConfig: false,
persist: false
}
})
}
};
</code></pre>
<h3 id="选项-1">选项</h3>
<h4 id="config">config</h4>
<p>自定义 <code>wrangler.toml</code> 或 <code>wrangler.json</code> 配置文件的路径。</p>
<h4 id="platformproxy-1">platformProxy</h4>
<p>模拟的 <code>platform.env</code> 本地绑定的首选项。完整的选项列表请参见 getPlatformProxy Wrangler API 文档。</p>
<h3 id="基本配置">基本配置</h3>
<p>此适配器需要在项目根目录中找到 wrangler.toml/wrangler.json 文件。它应该看起来像这样：</p>
<pre><code class="language-toml">/// file: wrangler.toml
name = "<your-service-name>"
account_id = "<your-account-id>"
main = "./.cloudflare/worker.js"
site.bucket = "./.cloudflare/public"
build.command = "npm run build"
compatibility_date = "2021-11-12"
workers_dev = true
</code></pre>
<p><code><your-service-name></code> 可以是任何名称。<code><your-account-id></code> 可以通过登录到您的 Cloudflare 仪表板 并从 URL 末尾获取：</p>
<pre><code>https://dash.cloudflare.com/<your-account-id>
</code></pre>
<blockquote>
<p>[!NOTE] 您应该将 <code>.cloudflare</code> 目录（或您为 <code>main</code> 和 <code>site.bucket</code> 指定的任何目录）添加到 <code>.gitignore</code> 中。</p>
</blockquote>
<p>如果您还没有安装 wrangler 并登录，需要先执行这些操作：</p>
<pre><code>npm i -g wrangler
wrangler login
</code></pre>
<p>然后，您可以构建并部署您的应用：</p>
<pre><code class="language-sh">wrangler deploy
</code></pre>
<h3 id="自定义配置">自定义配置</h3>
<p>如果您想使用 <code>wrangler.toml</code> 以外的配置文件，可以使用 <code>config</code> 选项 指定。</p>
<p>如果您想启用 Node.js 兼容性，可以在 <code>wrangler.toml</code> 中添加 "nodejs_compat" 标志：</p>
<pre><code class="language-toml">/// file: wrangler.toml
compatibility_flags = [ "nodejs_compat" ]
</code></pre>
<h3 id="运行时-api-1">运行时 API</h3>
<p><code>env</code> 对象包含您项目的 绑定，包括 KV/DO 命名空间等。它通过 <code>platform</code> 属性传递给 SvelteKit，同时还包括 <code>context</code>、<code>caches</code> 和 <code>cf</code>，这意味着您可以在 hooks 和端点中访问它：</p>
<pre><code class="language-js">// @errors: 7031
export async function POST({ request, platform }) {
const x = platform.env.YOUR_DURABLE_OBJECT_NAMESPACE.idFromName('x');
}
</code></pre>
<blockquote>
<p>[!NOTE] 对于环境变量，应优先使用 SvelteKit 内置的 <code>$env</code> 模块。</p>
</blockquote>
<p>要包含绑定的类型声明，请在您的 <code>src/app.d.ts</code> 中引用它们：</p>
<pre><code class="language-ts">/// file: src/app.d.ts
import { KVNamespace, DurableObjectNamespace } from '@cloudflare/workers-types';
declare global {
namespace App {
interface Platform {
+++ env?: {
YOUR_KV_NAMESPACE: KVNamespace;
YOUR_DURABLE_OBJECT_NAMESPACE: DurableObjectNamespace;
};+++
}
}
}
export {};
</code></pre>
<h4 id="本地测试-1">本地测试</h4>
<p>在开发和预览模式下，<code>platform</code> 属性中的 Cloudflare Workers 特定值会被模拟。本地 绑定 是基于您的 <code>wrangler.toml</code> 文件中的配置创建的，并在开发和预览期间用于填充 <code>platform.env</code>。使用适配器配置的 <code>platformProxy</code> 选项 可以更改绑定的首选项。</p>
<p>要测试构建，您应该使用 wrangler <strong>版本 3</strong>。构建完网站后，运行 <code>wrangler dev</code>。</p>
<h3 id="故障排除-1">故障排除</h3>
<h4 id="worker-大小限制">Worker 大小限制</h4>
<p>在部署到 workers 时，SvelteKit 生成的服务端会被打包成单个文件。如果您的 worker 在压缩后超过了 大小限制，Wrangler 将无法发布。通常您不太可能遇到这个限制，但某些大型库可能会导致这种情况。在这种情况下，您可以尝试通过仅在客户端导入这些库来减小 worker 的大小。更多信息请参见 FAQ。</p>
<h4 id="访问文件系统-1">访问文件系统</h4>
<p>您不能在 Cloudflare Workers 中使用 <code>fs</code> — 您必须 预渲染 相关路由。</p>
<h2 id="svelte-中文文档">Svelte 中文文档</h2>
<p>点击查看中文文档：</p>
<ul>
<li>SvelteKit Cloudflare Pages</li>
<li>SvelteKit Cloudflare Workers</li>
</ul>
<p>系统学习 Svelte，欢迎入手小册《Svelte 开发指南》。语法篇、实战篇、原理篇三大篇章带你系统掌握 Svelte！</p>
<p>此外我还写过 JavaScript 系列、TypeScript 系列、React 系列、Next.js 系列、冴羽答读者问等 14 个系列文章， 全系列文章目录：https://github.com/mqyqingfeng/Blog</p>
<p>欢迎围观我的“网页版朋友圈”、加入“冴羽·成长陪伴社群”，踏上“前端大佬成长之路”。</p><br><br>
来源：https://www.cnblogs.com/yayujs/p/18792331
頁:
[1]