1. 教培管家系统起步为什么环境搭建阶段就要把 AI Key 统一做教培管家这类全栈系统起步阶段最容易被忽略的不是页面写得好不好看而是「环境变量和 AI 通道」这两件事有没有一次性理顺。Next.js 16 的 App Router、Server Actions、Route Handlers 都能直接读环境变量如果你在第一天就把 AI 调用的 Key 散落在.env.local、config.toml、编辑器插件三个地方后面接排课问答、作业批改、家长话术生成时改一个 Key 要翻五个文件。我这次的做法是脚手架搭完立刻把 AI 能力收敛到 TaoToken 一个统一 Key 上。TaoToken 是一个面向开发者的 AI 模型 API 聚合通道你可以把它理解成「一个 Key 打通多家模型」的入口适合谁适合正在做全栈项目、需要在前端、后端、命令行工具里同时调用大模型的开发者。它提供兼容 OpenAI 风格的接口也有 Claude Code 这类编码工具的接入方式所以 Next.js 项目里用fetch能调终端里用编码 Agent 也能调。这一篇交付三样东西一份可复制的.env.local、一份config.toml骨架、以及启动后能跑通的连通性验证脚本。目标很明确——你跟着敲完npm run dev起来浏览器里能看到教培管家的首页终端里能确认 AI 通道是通的。数据库、Shadcn UI、RBAC 这些放到下一篇这篇只解决「跑起来 接得上」。2. TaoToken 前置准备拿 Key、认地址、分清两种接入形态在写任何配置之前先把 TaoToken 这边的准备工作做完。你需要一个可用的 API Key获取入口在控制台的 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite登录后新建一个 Key复制出来先存到密码管理器里页面上通常只完整显示一次。这个 Key 就是后面.env.local里要填的值。接着要区分两个地址很多人第一次会搞混用途地址说明官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册、看文档、进控制台API 基址https://taotoken.net/api代码里请求的 base URL不加 UTM注意 API 基址后面不要自己乱加/v1具体路径以接入文档为准。文档入口https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteTaoToken 有两种典型接入形态这篇都会覆盖第一种是「代码里直接调」也就是在 Next.js 的 Route Handler 或 Server Action 里用fetch请求https://taotoken.net/api适合做业务内的 AI 功能比如家长消息润色、课程描述生成。第二种是「编码工具接入」也就是把 Claude Code 这类命令行 Agent 指向 TaoToken 的通道用config.toml配置。这样你在终端里让 Agent 帮你写 Schema、改组件时走的是同一个 Key不用再单独买一份。提示Key 只放在本地.env.local和用户目录的config.toml里绝对不要提交到 Git。.env.local默认就在 Next.js 的.gitignore里但config.toml要你自己确认路径不在项目仓库内。3. 可复制配置.env.local 与 config.toml 骨架3.1 初始化 Next.js 16 脚手架先确认 Node 版本Next.js 16 建议用当前 LTSnode -v # 期望输出 v22.x 或更高然后创建项目交互式问答里 TypeScript、ESLint、Tailwind、App Router、src/目录都选上import alias 用默认的/*npx create-next-applatest edu-manager cd edu-manager装完先别急着改代码把 AI 相关的环境变量文件建好。3.2 .env.local 骨架在项目根目录新建.env.local内容如下。把sk-你的Key换成第 2 步拿到的真实 Key# ---- 数据库下一篇用先占位---- POSTGRES_URLpostgres://postgres:你的密码localhost:5432/edu_manager_db # ---- TaoToken 统一 AI 通道 ---- TAOTOKEN_API_KEYsk-你的Key TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_DEFAULT_MODELclaude-sonnet-4-5 # ---- 应用侧开关 ---- AI_ENABLEDtrue这里三个变量各有分工TAOTOKEN_API_KEY是身份TAOTOKEN_BASE_URL是通道地址TAOTOKEN_DEFAULT_MODEL是默认模型名。模型名请以接入文档里的可用列表为准不要照抄我写的这个不同时间可选的模型会变。为了让 TypeScript 认识这些变量在根目录建一个env.d.tsdeclare namespace NodeJS { interface ProcessEnv { POSTGRES_URL: string; TAOTOKEN_API_KEY: string; TAOTOKEN_BASE_URL: string; TAOTOKEN_DEFAULT_MODEL: string; AI_ENABLED: string; } }3.3 config.toml 骨架编码工具接入如果你打算在终端里用 Claude Code 这类 Agent 辅助开发需要在用户目录下配置。路径按系统区分macOS/Linux 是~/.claude/config.tomlWindows 是C:\Users\你的用户名\.claude\config.toml。骨架如下# TaoToken 统一通道接入编码工具 # 文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite [api] base_url https://taotoken.net/api api_key sk-你的Key [model] default claude-sonnet-4-5 max_tokens 8192 [behavior] stream true timeout_ms 60000base_url和api_key与.env.local保持一致这样代码侧和终端侧共用一份额度账单也好看。timeout_ms给到 60 秒是因为长上下文生成时短超时容易断流。注意config.toml里同样不要出现任何账号密码以外的敏感信息也不要把它放进项目目录被 Git 追踪。可以用git check-ignore确认一下。4. 验证请求写一个连通性检查 Route Handler配置写完必须验证不然等到业务代码报错时你分不清是 Key 问题还是逻辑问题。Next.js 16 的 App Router 里建一个 Route Handler 最直接。4.1 创建检查接口新建src/app/api/ai-check/route.tsimport { NextResponse } from next/server; export async function GET() { const apiKey process.env.TAOTOKEN_API_KEY; const baseUrl process.env.TAOTOKEN_BASE_URL; const model process.env.TAOTOKEN_DEFAULT_MODEL; if (!apiKey || !baseUrl) { return NextResponse.json( { ok: false, reason: 缺少 TAOTOKEN_API_KEY 或 TAOTOKEN_BASE_URL }, { status: 500 } ); } try { const res await fetch(${baseUrl}/v1/messages, { method: POST, headers: { Content-Type: application/json, x-api-key: apiKey, anthropic-version: 2023-06-01, }, body: JSON.stringify({ model, max_tokens: 64, messages: [{ role: user, content: 只回复两个字连通 }], }), }); const text await res.text(); return NextResponse.json({ ok: res.ok, status: res.status, model, preview: text.slice(0, 200), }); } catch (err) { return NextResponse.json( { ok: false, reason: (err as Error).message }, { status: 502 } ); } }这段代码做了三件事读环境变量、发一次最小请求、把状态码和返回片段吐出来。max_tokens给 64 是为了省钱省时间验证阶段不需要长回复。4.2 启动并访问npm run dev终端出现Ready in xxx ms后浏览器打开http://localhost:3000/api/ai-check成功时你会看到类似这样的 JSON{ ok: true, status: 200, model: claude-sonnet-4-5, preview: {\id\:\msg_xxx\,\content\:[{\type\:\text\,\text\:\连通\}]} }ok: true且status: 200说明 Key、基址、模型名三者都对上了。如果preview里出现的是错误信息而不是模型回复直接看第 5 节的排查表。4.3 顺手清理首页样板验证通过后把src/app/page.tsx换成教培管家的占位首页方便后面接着做布局export default function Home() { return ( main classNameflex min-h-screen flex-col items-center justify-center gap-4 p-24 h1 classNametext-4xl font-bold教培管家系统/h1 p classNametext-muted-foreground Next.js 16 全栈脚手架已就绪AI 通道已接通 /p /main ); }再访问http://localhost:3000看到标题就说明前端侧也正常了。5. 本篇常见错排查环境搭建阶段的报错基本集中在四类我按出现频率排一下。第一类401 / 403Key 无效。最常见的原因是.env.local里 Key 带了多余空格或引号。检查方式是console.log(apiKey.length)正常长度是固定的多一位少一位都不对。另一个原因是 Key 复制时漏了尾部字符重新去控制台复制一次即可。第二类404路径不对。如果你把baseUrl写成了https://taotoken.net/api/v1再拼/v1/messages就变成/api/v1/v1/messages。记住TAOTOKEN_BASE_URL只写到/api具体路径在代码里拼。不同接口的路径以接入文档为准。第三类模型名不存在。报错信息里通常会有model not found之类的字样。这时候去文档里核对当前可用的模型列表别用我示例里的名字硬套。模型名是区分大小写的。第四类改了.env.local但没生效。Next.js 只在启动时读一次环境变量改完必须重启npm run dev。我试过改完直接刷新页面结果一直用旧值白白排查了十分钟。现象大概率原因处理动作401 / 403Key 错误或带空格重新复制检查长度404base URL 多写了/v1只保留https://taotoken.net/apimodel not found模型名过期或拼错查文档核对可用列表改了配置无变化未重启 dev serverCtrlC 后重新npm run dev请求超时网络或 timeout 太短调大timeout_ms重试如果排查完还是不通直接去 API Keys 页面确认 Key 状态是否正常或者对照接入文档逐项核对请求头。文档里对请求头字段有明确说明x-api-key和anthropic-version这两个别漏。6. 下一步把统一 Key 用进真实业务与编码流脚手架和通道都通了之后接下来就是让它干活。两条路可以并行一条是业务侧在 Server Action 里封装一个callAI工具函数把TAOTOKEN_API_KEY和TAOTOKEN_BASE_URL收进去后面做家长消息润色、课程简介生成时直接调不用每次重复写请求头。模型对话的调试入口在这里https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite另一条是编码侧把config.toml配好后在终端里让 Agent 帮你写数据库 Schema、生成 Zod 校验、重构组件。长期做编码和 Agent 任务的话Coding Plan 更适合入口https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite下一篇会在这个脚手架上引入 Shadcn UI、搭 Dashboard 布局、设计 RBAC 相关的数据库 Schema。你现在要做的就是确认/api/ai-check返回ok: true然后把这篇文章里的.env.local和config.toml存好——它们是后面所有 AI 功能的地基。