环境变量与构建适配器

环境变量基础

环境变量是独立于代码的配置值，用于存储 API 密钥、数据库连接串等敏感信息。SvelteKit 在 .env 或 .env.local 文件中定义：

# .env.local
API_KEY=19f401ba-e8b0-48c4-8c77-b0ebb26d97fe
PUBLIC_SITE_URL=https://example.com

SvelteKit 提供四个模块来访问环境变量，按两个维度区分：

模块	可见性	时机
$env/static/private	仅服务端	构建时内联
$env/static/public	服务端 + 客户端	构建时内联
$env/dynamic/private	仅服务端	运行时读取
$env/dynamic/public	服务端 + 客户端	运行时读取

static：构建时内联

static 模块在构建时把变量值直接内联到代码中。值改变后需要重新构建。

// src/routes/+page.server.js
import { API_KEY } from '$env/static/private';

export async function load() {
	const data = await fetch('https://api.example.com/data', {
		headers: { 'Authorization': `Bearer ${API_KEY}` }
	});
	return { data: await data.json() };
}

公开变量用 $env/static/public，可以被客户端代码访问：

<script>
	import { PUBLIC_SITE_URL } from '$env/static/public';
</script>

<footer>© {new Date().getFullYear()} {PUBLIC_SITE_URL}</footer>

dynamic：运行时读取

dynamic 模块在运行时读取环境变量，值改变后不需要重新构建。适合容器化部署、Docker 等场景：

// src/routes/+page.server.js
import { env } from '$env/dynamic/private';

export async function load() {
	const dbUrl = env.DATABASE_URL;
	// 连接数据库...
}

import { env } from '$env/dynamic/public';

const apiUrl = env.PUBLIC_API_URL;

场景	推荐
值不变	static（构建时内联，支持 tree-shaking）
值随环境变	dynamic（运行时读取，不需重新构建）

在 app.html 中使用

公开环境变量可以在 app.html 模板中使用：

<script async src="https://www.googletagmanager.com/gtag/js?id=%sveltekit.env.PUBLIC_GA_ID%"></script>

%sveltekit.env.PUBLIC_GA_ID% 在渲染时被替换为环境变量值。

构建应用

构建分两个阶段：

npm run build

1. Vite 构建阶段：优化服务端代码、浏览器代码和 Service Worker，执行预渲染
2. 适配器阶段：把构建产物适配为目标平台的格式

构建后可以预览：

npm run preview

import { building } from '$app/environment';
import { initDB } from '$lib/server/database';

if (!building) {
	initDB();
}

适配器是什么

适配器是 SvelteKit 的构建插件，把通用构建产物转换为目标平台的部署格式。在 svelte.config.js 中配置：

import adapter from '@sveltejs/adapter-auto';
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';

const config = {
	preprocess: vitePreprocess(),
	kit: {
		adapter: adapter()
	}
};

export default config;

官方适配器

适配器	用途
adapter-auto	自动检测部署平台
adapter-node	Node 服务器（含 Docker）
adapter-static	纯静态站点（SSG）
adapter-vercel	Vercel 平台
adapter-netlify	Netlify 平台
adapter-cloudflare	Cloudflare Workers/Pages

adapter-auto

新项目默认用 adapter-auto，它自动检测部署平台：

import adapter from '@sveltejs/adapter-auto';

const config = {
	kit: {
		adapter: adapter()
	}
};

部署到 Vercel 时自动用 Vercel 适配器，部署到 Netlify 时自动用 Netlify 适配器。如果检测不到，构建会提示你安装合适的适配器。

adapter-node

部署到自己的服务器或 Docker 容器时用 adapter-node：

import adapter from '@sveltejs/adapter-node';

const config = {
	kit: {
		adapter: adapter()
	}
};

构建后生成一个 Node 服务器，用 node build 启动。支持环境变量配置端口和源地址：

PORT=3000 ORIGIN=https://example.com node build

adapter-static

纯静态站点用 adapter-static。所有页面必须预渲染：

import adapter from '@sveltejs/adapter-static';

const config = {
	kit: {
		adapter: adapter({
			pages: 'build'  // 输出目录
		})
	}
};

根布局需要设 export const prerender = true 或 prerender = 'auto'。

adapter-vercel

Vercel 部署用 adapter-vercel，支持边缘函数和 ISR：

import adapter from '@sveltejs/adapter-vercel';

const config = {
	kit: {
		adapter: adapter()
	}
};

页面级可以配置运行时：

// src/routes/+page.js
export const config = {
	runtime: 'edge'  // 部署到边缘节点
};

选择适配器

部署目标	适配器
Vercel	adapter-vercel 或 adapter-auto
Netlify	adapter-netlify 或 adapter-auto
Cloudflare	adapter-cloudflare
自有服务器 / Docker	adapter-node
静态托管	adapter-static
不确定	adapter-auto

平台特定上下文

部分适配器提供 platform 对象，包含平台特有的信息。比如 Cloudflare Workers 的 KV 存储：

// src/routes/+server.js
export async function GET({ platform }) {
	const value = await platform.env.MY_KV.get('key');
	return new Response(value);
}

具体有哪些 platform 属性，参考各适配器的文档。

本节回顾

• 四种环境变量模块：static/private、static/public、dynamic/private、dynamic/public
• 私有变量只在服务端可用，公开变量以 PUBLIC_ 开头，客户端也能访问
• static 在构建时内联值，dynamic 在运行时读取
• 构建分两步：Vite 优化 + 适配器转换
• 适配器决定部署格式：auto（自动）、node（服务器）、static（静态）、vercel/netlify/cloudflare（平台）
• 用 $app/environment 的 building 变量保护构建时不应执行的代码
• platform 对象提供平台特有信息（如 Cloudflare KV）