Bun + SvelteKit 适配器安装指南

Bun + SvelteKit 适配器安装指南

本文将详细介绍如何在 Bun 运行时中安装和配置 SvelteKit 适配器（svelte-adapter-bun），并解决常见问题。通过本教程，您将快速完成项目环境搭建与生产部署。

社区插件没有fallback,如果静态文件找不到就直接换成static适配器插件好了。

检查就看打包后的build或者dist等目录下是否有index,html静态文件即可。

---

目录

1. 环境准备
2. 创建 SvelteKit 项目
3. 安装与配置适配器
4. 构建与运行
5. 常见问题与解决方案
6. 参考文档
7. 版权声明

---

1. 环境准备

1.1 安装 Bun

Bun 是一个高性能的 JavaScript 运行时，需全局安装：

curl -fsSL https://bun.sh/install | bash

验证安装：

bun --version  # 输出类似：1.0.23

---

2. 创建 SvelteKit 项目

使用 Bun 初始化 SvelteKit 项目：

bun create svelte@latest my-sveltekit-app

根据提示选择配置：

• 模板：推荐 Skeleton project（基础骨架项目）
• TypeScript：选择 Yes
• 额外选项：按需启用 ESLint/Prettier 。

安装依赖：

cd my-sveltekit-app
bun install

---

3. 安装与配置适配器

3.1 安装 svelte-adapter-bun

SvelteKit 适配器需显式安装：

bun add -D svelte-adapter-bun

3.2 修改 SvelteKit 配置

在 svelte.config.js 中替换默认适配器：

import adapter from 'svelte-adapter-bun';
import { vitePreprocess } from '@sveltejs/kit/vite';

export default {
  kit: {
    adapter: adapter({
      out: 'build',     // 构建输出目录
      precompress: true // 启用 Gzip/Brotli 压缩
    })
  },
  preprocess: vitePreprocess()
};

3.3 禁用 SSR（可选）

在 src/routes/+layout.ts 中添加：

export const prerender = true;
export const ssr = false;  // 禁用服务端渲染

---

4. 构建与运行

4.1 开发模式

启动开发服务器：

bun run dev -- --bun  # 使用 Bun 运行时

4.2 生产构建

生成静态文件至 build 目录：

bun run build

4.3 启动生产服务器

运行构建后的代码：

bun run start  # 默认加载 build/index.js

---

5. 常见问题与解决方案

5.1 index.html 未生成

• 原因：构建路径未正确配置。
• 解决：检查 svelte.config.js 中 out 路径是否与构建目录一致 。

5.2 动态路由失效

• 原因：未配置客户端路由回退。
• 解决：在 svelte.config.js 中设置 fallback: 'index.html' 。

5.3 静态资源加载失败

• 原因：资源路径未正确引用。
• 解决：确保静态文件（CSS/JS）放置在 static 目录，并通过绝对路径引用（如 /static/logo.png） 。

5.4 适配器版本冲突

• 原因：svelte-adapter-bun 版本与 SvelteKit 不兼容。
• 解决：使用最新版本：

bun add -D svelte-adapter-bun@latest

---

6. 参考文档

• SvelteKit 官方适配器文档
• Bun 运行时配置指南
• SvelteKit 静态生成最佳实践

---

版权声明
本文由 优快云 用户原创，未经许可禁止转载。如需引用请注明出处并附原文链接。
© 2025 优快云 版权所有，保留所有权利。

**注意事项**：  
- 若需部署到云服务（如 Vercel），需改用 `@sveltejs/adapter-vercel`，参考官方文档调整配置。  
- 使用 `svelte-adapter-bun` 时需确保 Bun 版本 ≥ 1.0.0。