1. 为什么我还在用 Svelte 搭 SPA一个真实的重构场景如果你正在找一个「编译完几乎没有运行时」的前端框架Svelte 值得认真试一次。它和 React、Vue 最大的区别在于组件在构建阶段就被编译成原生 DOM 操作代码浏览器里不需要加载一整套框架运行时。这意味着同样一个仪表盘页面Svelte 打包出来的 JS 体积往往只有 React 方案的一半甚至更少首屏加载和交互响应都更干脆。这篇要交付的是一条完整链路用 Vite 初始化 Svelte 项目接入 Tailwind CSS 做样式用 Svelte 内置 store 管状态再补上路由最后把 TaoToken 的统一 Key/API 通道配置进项目让前端在本地就能调通模型接口。适合谁适合已经会一点 JS、想从零跑通一个高性能 SPA、并且希望顺手把 AI 接口调用链路也搭好的开发者。整个过程我会给出可复制的目录结构、依赖清单、配置片段和验证命令目标是一次跑通开发环境并确认 API 调用链路真的可用。我试过在几个中小型后台项目里用这套组合踩过的坑主要集中在 Tailwind 的 content 扫描路径和 API Key 的注入方式上后面会逐个说清楚。2. TaoToken 前置准备拿到统一 Key 与 API 通道在写任何前端代码之前先把「后端能力」准备好。TaoToken 在这里扮演的是一个统一的模型调用入口你不需要为每个模型厂商单独维护一套 Key 和请求格式而是用同一个 Key、同一个 API 地址去调用不同模型。对 SPA 项目来说这能省掉大量在环境变量和请求封装上的重复劳动。你需要做两件事。第一注册并登录后进入控制台创建一个 API Key。第二记住两个地址官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基础地址是 https://taotoken.net/api 这个不加 UTM 参数直接用于代码里的 baseURL。创建 Key 的入口在控制台的 API Keys 页面建议直接打开 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。生成后先复制保存它只会完整显示一次。如果你后面要做长期编码或 Agent 类任务可以顺带了解 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。注意Key 属于敏感凭证绝对不要硬编码进前端源码提交到仓库。SPA 的正确做法是通过 Vite 的环境变量注入并且只用于本地开发调试生产环境应该走你自己的后端代理。3. 从零初始化 Svelte Vite 项目先确认 Node.js 版本不低于 18.x推荐用 pnpm 提升安装效率。下面这套命令我实测下来最稳npm create vitelatest my-svelte-spa -- --template svelte cd my-svelte-spa pnpm install初始化完成后目录结构大致是这样my-svelte-spa/ ├── index.html ├── package.json ├── vite.config.js ├── svelte.config.js ├── src/ │ ├── main.js │ ├── App.svelte │ ├── app.css │ └── lib/ │ ├── stores/ │ └── components/ └── public/依赖清单里核心是svelte和vite路由用svelte-spa-router轻量、适合纯 SPA样式用 Tailwind。一次性装齐pnpm add svelte-spa-router pnpm add -D tailwindcss postcss autoprefixer npx tailwindcss init -p这里有个容易忽略的点svelte-spa-router是基于 hash 的路由不需要服务端配置 rewrite部署到静态托管最省心。如果你更想要 history 模式可以换sveltejs/kit但那套更重本文聚焦纯 SPA先用前者。4. 接入 Tailwind CSS 并配置扫描路径Tailwind 接入的关键在content字段它决定了哪些文件里的类名会被保留。Svelte 项目必须把.svelte后缀写进去否则你写的类名会被当成未使用而摇掉页面样式全丢。修改tailwind.config.js/** type {import(tailwindcss).Config} */ export default { content: [ ./index.html, ./src/**/*.{js,svelte,html} ], theme: { extend: { colors: { brand: #4f46e5 } } }, plugins: [] }然后在src/app.css里引入三层指令并加一点全局基础样式tailwind base; tailwind components; tailwind utilities; body { margin: 0; font-family: Inter, system-ui, sans-serif; background-color: #f8fafc; }最后确认src/main.js引入了这个 CSSimport ./app.css import App from ./App.svelte const app new App({ target: document.getElementById(app) }) export default app写一个组件验证 Tailwind 是否生效!-- src/lib/components/Hero.svelte -- div classflex items-center justify-center h-screen bg-gradient-to-br from-indigo-50 to-blue-100 h1 classtext-4xl font-bold text-gray-800Svelte SPA 已就绪/h1 /div启动pnpm dev如果看到渐变背景和居中标题说明 Tailwind 链路通了。如果样式没出来九成是content路径写错回去检查后缀。5. 状态管理与路由store svelte-spa-routerSvelte 的状态管理是内置的不需要额外库。用writable创建一个全局 store// src/lib/stores/userStore.js import { writable } from svelte/store export const user writable({ name: , isLoggedIn: false })组件里用$前缀自动订阅不用手动 subscribe/unsubscribe!-- src/lib/components/LoginButton.svelte -- script import { user } from ../stores/userStore /script {#if $user.isLoggedIn} button classbg-green-500 hover:bg-green-600 px-4 py-2 rounded text-white on:click{() ($user { name: , isLoggedIn: false })} 退出 /button {:else} button classbg-brand hover:opacity-90 px-4 py-2 rounded text-white on:click{() ($user { name: 张三, isLoggedIn: true })} 登录 /button {/if}路由部分在App.svelte里挂载 Router并定义页面映射!-- src/App.svelte -- script import Router from svelte-spa-router import Home from ./lib/pages/Home.svelte import Dashboard from ./lib/pages/Dashboard.svelte const routes { /: Home, /dashboard: Dashboard } /script Router {routes} /Dashboard.svelte里可以读取 store 做简单的访问控制!-- src/lib/pages/Dashboard.svelte -- script import { user } from ../stores/userStore /script div classp-6 max-w-md mx-auto h2 classtext-xl font-semibold mb-4仪表盘/h2 {#if $user.isLoggedIn} p欢迎回来{$user.name}/p {:else} p classtext-gray-500请先登录/p {/if} /div这套组合的好处是依赖极少路由一个包状态零依赖打包体积自然小。6. TaoToken 配置骨架settings.json 与 config.toml现在把 TaoToken 的 API 通道接进来。前端项目里我建议用 Vite 的环境变量管理 Key再封装一个请求模块。在项目根目录创建.env.localVITE_TAOTOKEN_API_BASEhttps://taotoken.net/api VITE_TAOTOKEN_API_KEY你的Key然后写一个统一的请求封装// src/lib/api/client.js const baseURL import.meta.env.VITE_TAOTOKEN_API_BASE const apiKey import.meta.env.VITE_TAOTOKEN_API_KEY export async function chatCompletion(messages, model gpt-4o-mini) { const res await fetch(${baseURL}/v1/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${apiKey} }, body: JSON.stringify({ model, messages }) }) if (!res.ok) { const err await res.text() throw new Error(请求失败 ${res.status}: ${err}) } return res.json() }如果你同时在用支持settings.json或config.toml的工具比如某些 CLI 或编辑器插件可以按下面的骨架填写。settings.json形式{ apiBase: https://taotoken.net/api, apiKey: 你的Key, defaultModel: gpt-4o-mini }config.toml形式[api] base_url https://taotoken.net/api api_key 你的Key default_model gpt-4o-mini注意这两个配置文件里的 Key 同样不要提交到公开仓库建议加入.gitignore或者用占位符配合本地覆盖。7. 验证请求本地跑通一次模型调用配置写完了必须验证链路真的通。在Home.svelte里加一个按钮触发调用!-- src/lib/pages/Home.svelte -- script import { chatCompletion } from ../api/client let reply let loading false async function handleCall() { loading true try { const data await chatCompletion([ { role: user, content: 用一句话介绍 Svelte } ]) reply data.choices?.[0]?.message?.content ?? 无返回内容 } catch (e) { reply e.message } finally { loading false } } /script div classp-8 button classbg-brand text-white px-4 py-2 rounded on:click{handleCall} disabled{loading} {loading ? 请求中... : 测试 TaoToken 调用} /button {#if reply} p classmt-4 text-gray-700{reply}/p {/if} /div启动pnpm dev点击按钮。成功的话你会看到模型返回的一句话介绍如果报 401说明 Key 没读到检查.env.local是否被 Vite 加载改完环境变量要重启 dev server如果报 404检查 baseURL 是否多了或少了/v1路径。想先在网页里直接验证模型是否可用可以打开模型对话页面https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。8. 本篇常见错误排查第一个高频问题Tailwind 类名不生效。原因几乎都是content没包含.svelte或者app.css没在main.js里引入。改完配置记得重启 dev server。第二个环境变量读不到。Vite 只暴露以VITE_开头的变量且修改.env.local后必须重启。用console.log(import.meta.env.VITE_TAOTOKEN_API_BASE)确认。第三个路由跳转 404。svelte-spa-router用 hash 模式地址形如/#/dashboard。如果你直接访问/dashboard会 404这是预期行为不是 bug。第四个请求跨域。本地开发时如果浏览器报 CORS先确认你请求的是https://taotoken.net/api而不是别的地址如果仍有问题检查是否在请求头里漏了Authorization。第五个Key 泄露风险。任何时候都不要把真实 Key 写进App.svelte或提交到 Git。生产环境请通过后端转发请求前端只调用你自己的接口。9. 下一步把链路固化下来到这里一个能跑通模型调用的 Svelte SPA 骨架就完成了。接下来你可以把chatCompletion封装成更完整的服务层加上流式输出、错误重试和 loading 状态也可以把 store 拆得更细按业务模块管理状态。如果你打算长期在这个项目里做编码或 Agent 类功能建议把 Key 管理和调用配额统一到 Coding Plan 上入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。接入文档里有更完整的参数说明和示例需要时对照查阅https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。把.env.local加进.gitignore然后提交你的第一版代码这条链路就算真正落地了。