SvelteKit 配置可直接写入 vite.config.js

为什么这个变化现在很重要

自 SvelteKit 首个稳定版发布以来，框架一直依赖独立的 svelte.config.js 文件来处理适配器、预渲染选项和预处理器等配置。虽然这种分离在 SvelteKit 还在摸索与 Vite 的关系时是合理的，但也带来了一个小小的摩擦点：

需要同步维护两个配置文件——在调整 SSR、环境变量或自定义 Vite 插件时，你往往不得不同时打开 svelte.config.js 和 vite.config.js。

工具链困惑——IDE 扩展有时会将这两个文件视为无关的，导致对未知属性的虚假警告。

引导开销——新贡献者必须学习哪些设置属于哪个文件，这增加了入职时的认知负担。

通过允许 SvelteKit 配置以 sveltekit 键嵌入到 vite.config.js 中，Svelte 团队有效地合并了这两个配置面。这对于 monorepo 或当你已经有一个复杂的 Vite 配置时（例如，多入口点、自定义别名或共享插件）特别方便。现在你可以在一个地方看到全貌，Vite 开发服务器会自动拾取任何 SvelteKit 特定的调整，无需额外的配置文件。

新的 API 是什么样的

博客文章展示了一个最小示例，用单个 vite.config.js 替换了典型的 svelte.config.js。以下是我如何迁移一个全新的 SvelteKit 项目：

// vite.config.js
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';
import { visualizer } from 'rollup-plugin-visualizer';

// Old separate svelte.config.js (for reference)
// export default {
//   kit: {
//     adapter: adapterNode(),
//     prerender: { default: true }
//   }
// };

export default defineConfig({
  plugins: [
    sveltekit({
      // All SvelteKit options go here
      kit: {
        // The adapter you were using before
        adapter: require('@sveltejs/adapter-node')(),
        // Keep your prerender defaults
        prerender: { default: true },
        // You can still add vite-specific overrides inside
        // the same object if you need them
        vite: {
          // Example: custom environment variable handling
          define: {
            __APP_VERSION__: JSON.stringify('1.0.0')
          }
        }
      }
    }),
    // Any other Vite plugins stay where they belong
    visualizer({ filename: './stats.html' })
  ],
  // General Vite config stays at the top level
  resolve: {
    alias: {
      $components: '/src/lib/components',
      $utils: '/src/lib/utils'
    }
  },
  server: {
    port: 5173,
    strictPort: true
  }
});

需要注意几点：

从 @sveltejs/kit/vite 导入 sveltekit 插件——这与运行 npm init svelte@next 时 Vite 自动添加的插件相同，但现在你需要显式调用它。

将所有 SvelteKit 特定的键包装在 kit 对象内——这与旧的 svelte.config.js 的结构一致。

你仍然可以在配置顶层暴露 Vite 专用设置（如 resolve.alias 或 server.port），所有内容放在一个文件中。

如果你已经有一个带自定义插件的 vite.config.js，只需将 sveltekit 调用添加到 plugins 数组中，并将 kit 块移入其选项。不再会有"重复适配器定义"或"缺少预渲染标志"的错误。

这如何影响常见工作流

以前你会编辑 svelte.config.js：

// svelte.config.js
import adapterStatic from '@sveltejs/adapter-static';
export default {
  kit: {
    adapter: adapterStatic(),
    // …
  }
};

现在你在 vite.config.js 中完成：

// vite.config.js (excerpt)
sveltekit({
  kit: {
    adapter: require('@sveltejs/adapter-static')(),
    // …
  }
})

这个变化是语法层面的，但它消除了在预发布和生产环境切换适配器时需要保持两个文件同步的需求。

由于适配器配置位于 Vite 插件调用内部，你可以直接引用 Vite 的 process.env（或更新的 import.meta.env）：

kit: {
  adapter: require('@sveltejs/adapter-node')({
    env: {
      // Pass a runtime variable to the adapter
      NODE_ENV: process.env.NODE_ENV
    }
  })
}

这比将 dotenv 拉到一个单独的 svelte.config.js 中要自然得多。

如果你需要像 svelte-preprocess 这样的预处理器，仍然导入它并传递给 sveltekit 插件：

import preprocess from 'svelte-preprocess';

sveltekit({
  kit: {
    // …
  },
  preprocess
})

API 保持不变；唯一的区别是文件位置。

没有变化是没有代价的。以下是我在迁移过程中遇到的实际问题：

新手的学习曲线——只读过旧教程的开发者可能会在找不到 svelte.config.js 时感到困惑。文档现在需要明确说明新位置。

工具链缺口——一些社区插件（例如，寻找 svelte.config.js 的 ESLint 配置）仍然假定旧文件存在。在我的 monorepo 中，我不得不添加一个小的垫片文件来重新导出配置，以让这些工具正常工作。

版本锁定——新功能与 SvelteKit 1.28+（随 2026 年 7 月版本一起发布）绑定。早于该版本的被锁定项目将需要升级，这可能涉及其他破坏性变更。

总的来说，缺点主要是关于更新文档和一些边缘情况工具集成，而不是关于运行时行为。

在快速测试分支之后，我决定将我的生产 SvelteKit 应用升级到 2026 年 7 月版本。迁移每个仓库花费不到 15 分钟，生成的 vite.config.js 感觉更清晰：从适配器到自定义 Vite 插件，所有内容都在一个屋檐下。在我们已经维护共享 Vite 配置的环境中（例如，同时发布 React 和 Svelte 组件的设计系统库），这种整合减少了对新员工的心理开销。

如果你是一个全新的 SvelteKit 项目，我建议直接使用它——完全跳过 svelte.config.js，将配置保留在 vite.config.js 中。对于现有项目，权衡单一配置文件的好处与更新任何期望 svelte.config.js 的工具链的努力。在大多数情况下，升级是值得的，特别是因为它使 SvelteKit 与更广泛的 Vite 生态系统保持一致，并为未来的整合铺平了道路。