附錄

常見問題

在 GitHub 上編輯此頁面

其他資源永久連結

請參閱 Svelte 常見問題和 vite-plugin-svelte 常見問題，以取得這些程式庫衍生問題的解答。

我可以使用 SvelteKit 製作什麼？永久連結

SvelteKit 可用於建立大多數類型的應用程式。SvelteKit 開箱即用支援許多功能，包括

使用 load 函式和 API 路由的動態頁面內容。
使用伺服器端渲染 (SSR) 的 SEO 友善動態內容。
使用 SSR 和表單動作的使用者友善漸進增強互動式頁面。
使用預先渲染的靜態頁面。

SvelteKit 也可透過轉接器部署到廣泛的託管架構。在使用 SSR（或在沒有預先渲染的情況下新增伺服器端邏輯）的情況下，這些函式將會調整到目標後端。一些範例包括

使用 Node.js 後端的自架動態網路應用程式。
使用後端載入器和部署為遠端函式的 API 的無伺服器網路應用程式。請參閱零組態部署以取得熱門部署選項。
靜態預先渲染網站，例如部落格或託管在 CDN 或靜態主機上的多頁網站。靜態產生的網站會在沒有後端的情況下出貨。
單頁應用程式 (SPA) 使用客戶端路由和渲染，適用於 API 驅動的動態內容。SPA 在沒有後端的情況下發布，且不會在伺服器端渲染。當將 SvelteKit 與使用 PHP、.Net、Java、C、Golang、Rust 等語言編寫的應用程式綑綁在一起時，通常會選擇此選項。
上述選項的組合；有些路由可以是靜態的，而有些路由可以使用後端函式來擷取動態資訊。這可以使用頁面選項來設定，其中包含選擇不使用 SSR 的選項。

為了支援 SSR，需要一個 JS 後端，例如基於 Node.js 或 Deno 的伺服器、無伺服器函式或邊緣函式。

也可以撰寫自訂的轉接器或利用社群轉接器將 SvelteKit 部署到更多平台，例如專門的伺服器環境、瀏覽器擴充功能或原生應用程式。請參閱整合以取得更多範例和整合。

我該如何將 HMR 與 SvelteKit 一起使用？永久連結

SvelteKit 預設啟用 HMR，由 svelte-hmr 提供支援。如果您看過 Rich 在 2020 年 Svelte 高峰會上的簡報，您可能看過功能更強大的 HMR 版本。此示範啟用了 svelte-hmr 的 preserveLocalState 旗標。此旗標現在預設為關閉，因為它可能會導致意外的行為和臨界情況。但別擔心，您仍然可以在 SvelteKit 中使用 HMR！如果您想保留本機狀態，可以使用 svelte-hmr 頁面上記載的 @hmr:keep 或 @hmr:keep-all 指令。

我該如何將 package.json 中的詳細資訊包含在我的應用程式中？永久連結

您無法直接需要 JSON 檔案，因為 SvelteKit 預期 svelte.config.js 是 ES 模組。如果您想在應用程式中包含應用程式的版本號碼或其他來自 package.json 的資訊，您可以這樣載入 JSON

svelte.config.js

ts
import { readFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';

const path = fileURLToPath(new URL('package.json', import.meta.url));
const pkg = JSON.parse(readFileSync(path, 'utf8'));

我該如何修正我在嘗試包含套件時遇到的錯誤？永久連結

與包含函式庫相關的大部分問題都是因為包裝不正確所導致。您可以透過在 publint 網站中輸入函式庫，來檢查函式庫的包裝是否與 Node.js 相容。

在檢查函式庫是否正確包裝時，請記住以下幾件事

exports 優先於其他進入點欄位，例如 main 和 module。新增 exports 欄位可能無法向後相容，因為它會阻止深度匯入。
ESM 檔案應以 .mjs 結尾，除非設定 "type": "module"，在這種情況下，CommonJS 檔案應以 .cjs 結尾。
如果未設定 exports，則應定義 main。它應為 CommonJS 或 ESM 檔案，並遵守前一個項目符號。如果定義了 module 欄位，則它應參照 ESM 檔案。
Svelte 元件應分發為未編譯的 .svelte 檔案，且套件中的任何 JS 都只能寫成 ESM。自訂指令碼和樣式語言，例如 TypeScript 和 SCSS，應分別預處理為純粹的 JS 和 CSS。我們建議使用 svelte-package 來包裝 Svelte 函式庫，它會為您執行此操作。

當函式庫分發 ESM 版本時，它們在使用 Vite 的瀏覽器中效果最佳，特別是如果它們是 Svelte 元件函式庫的依賴項時。您可能希望建議函式庫作者提供 ESM 版本。但是，CommonJS (CJS) 依賴項也應該可以正常運作，因為預設情況下，vite-plugin-svelte 會要求 Vite 使用 esbuild 預先將它們打包，以將它們轉換為 ESM。

如果您仍然遇到問題，我們建議同時搜尋 Vite 問題追蹤器和有問題的函式庫的追蹤器。有時，透過調整 optimizeDeps 或 ssr 設定值，可以解決問題，不過我們建議這只是暫時解決方案，最好修復有問題的函式庫。

我該如何將檢視轉場 API 與 SvelteKit 搭配使用？permalink

雖然 SvelteKit 沒有與檢視轉場的特定整合，但您可以在 onNavigate 中呼叫 document.startViewTransition，以在每個用戶端導覽時觸發檢視轉場。

ts
import { onNavigate } from '$app/navigation';

onNavigate((navigation) => {
Property 'startViewTransition' does not exist on type 'Document'.2339Property 'startViewTransition' does not exist on type 'Document'.	if (!document.startViewTransition) return;

	return new Promise((resolve) => {
		document.startViewTransition(async () => {
			resolve();
			await navigation.complete;
		});
	});
});

如需更多資訊，請參閱 Svelte 部落格上的 "解鎖檢視轉場"。

我該如何將 X 與 SvelteKit 搭配使用？permalink

請確定您已閱讀關於整合的說明文件部分。如果您仍然遇到問題，以下是常見問題的解決方案。

我該如何設定資料庫？permalink

將查詢資料庫的程式碼放入伺服器路由中，不要在 .svelte 檔案中查詢資料庫。您可以建立一個 db.js 或類似的程式碼，立即設定一個連線，並讓客戶端可以在整個應用程式中作為單例存取。您可以在 hooks.server.js 中執行任何一次性設定程式碼，並將資料庫輔助程式匯入任何需要它們的端點。

如何使用僅限於客戶端的函式庫，而它依賴於文件或視窗？永久連結

如果您需要存取 document 或 window 變數，或需要程式碼僅在客戶端執行，您可以將它包在 browser 檢查中

ts
import { browser } from '$app/environment';

if (browser) {
	// client-only code here
}

如果您想在元件首次呈現在 DOM 中後執行程式碼，您也可以在 onMount 中執行程式碼

ts
import { onMount } from 'svelte';

onMount(async () => {
	const { method } = await import('some-browser-only-library');
	method('hello world');
});

如果您想使用的函式庫沒有副作用，您也可以靜態匯入它，它將在伺服器端建置中被樹狀搖晃，其中 onMount 將自動替換為空操作

ts
import { onMount } from 'svelte';
import { method } from 'some-browser-only-library';

onMount(() => {
	method('hello world');
});

最後，您也可以考慮使用 {#await} 區塊

index.svelte

<script>
	import { browser } from '$app/environment';

	const ComponentConstructor = browser ?
		import('some-browser-only-library').then((module) => module.Component) :
		new Promise(() => {});
</script>

{#await ComponentConstructor}
	<p>Loading...</p>
{:then component}
	<svelte:component this={component} />
{:catch error}
	<p>Something went wrong: {error.message}</p>
{/await}

index.svelte

<script lang="ts">
	import { browser } from '$app/environment';
	
	const ComponentConstructor = browser
		? import('some-browser-only-library').then((module) => module.Component)
		: new Promise(() => {});
</script>

{#await ComponentConstructor}
	<p>Loading...</p>
{:then component}
	<svelte:component this={component} />
{:catch error}
	<p>Something went wrong: {error.message}</p>
{/await}

如何使用不同的後端 API 伺服器？永久連結

您可以使用 event.fetch 從外部 API 伺服器請求資料，但請注意您需要處理 CORS，這將導致複雜情況，例如通常需要請求預先傳送，導致延遲較高。對單獨子網域的請求也可能由於額外的 DNS 查詢、TLS 設定等而增加延遲。如果您想使用此方法，您可能會發現 handleFetch 有幫助。

另一種方法是設定代理伺服器以繞過 CORS 問題。在製作階段，您會將類似於 /api 的路徑改寫為 API 伺服器；對於本機開發，請使用 Vite 的 server.proxy 選項。

如何在製作階段設定改寫將取決於您的部署平台。如果改寫不是選項，您也可以新增 API 路由

src/routes/api/[...path]/+server.js

ts
/** @type {import('./$types').RequestHandler} */
export function GET({ params, url }) {
	return fetch(`https://my-api-server.com/${params.path + url.search}`);
}

src/routes/api/[...path]/+server.ts

ts
import type { RequestHandler } from './$types';

export const GET: RequestHandler = ({ params, url }) => {
	return fetch(`https://my-api-server.com/${params.path + url.search}`);
};

（請注意，您可能還需要代理 POST/PATCH 等要求，並根據您的需求轉發 request.headers。）

如何使用中間件？永久連結

adapter-node 建立一個中間件，您可以在生產模式中與自己的伺服器一起使用。在開發中，您可以使用 Vite 外掛程式將中間件新增到 Vite。例如

ts
import { sveltekit } from '@sveltejs/kit/vite';

/** @type {import('vite').Plugin} */
const myPlugin = {
	name: 'log-request-middleware',
	configureServer(server) {
		server.middlewares.use((req, res, next) => {
			console.log(`Got request ${req.url}`);
			next();
		});
	}
};

/** @type {import('vite').UserConfig} */
const config = {
	plugins: [myPlugin, sveltekit()]
};

export default config;

請參閱 Vite 的 configureServer 文件，以取得更多詳細資訊，包括如何控制排序。

它是否適用於 Yarn 2？永久連結

有點。Plug'n'Play 功能，又稱「pnp」，已中斷（它偏離了 Node 模組解析演算法，而且尚未與 SvelteKit 使用的原生 JavaScript 模組一起使用，以及越來越多的套件）。您可以在 .yarnrc.yml 檔案中使用 nodeLinker: 'node-modules' 來停用 pnp，但可能更容易使用 npm 或 pnpm，它們的速度和效率類似，但沒有相容性問題。

如何與 Yarn 3 一起使用？永久連結

目前，最新 Yarn（版本 3）中的 ESM 支援被認為是實驗性的。

以下內容似乎有效，但您的結果可能有所不同。

首先建立一個新的應用程式

yarn create svelte myapp
cd myapp

並啟用 Yarn Berry

yarn set version berry
yarn install

Yarn 3 全域快取永久連結

Yarn Berry 更有趣的其中一個功能是能夠為套件擁有單一的全域快取，而不是在磁碟上為每個專案擁有多個副本。然而，將 enableGlobalCache 設定為 true 會導致建置失敗，因此建議將以下內容新增到 .yarnrc.yml 檔案

yaml
nodeLinker: node-modules

這將導致套件下載到本地的 node_modules 目錄，但避免上述問題，並且是您在這個時間點使用 Yarn 版本 3 的最佳選擇。

上一個類型

下一步整合