企业官网建设流程全解析

做AI应用开发这段时间，我越来越确信一个反直觉的结论：这类项目最大的风险不在模型效果，而在“数据形状”本身。我原本一直用裸JavaScript写一个智能体项目，功能起来很快，但越往后越不对劲——模型偶尔返回一个缺字段的JSON，工具调用的参数和函数实际期望对不上，异步编排里一个空数组把整条链路带崩。最近我把项目迁到了TypeScript，恰好用上TS5.7这个版本，跑了一个多月后翻日志，发现此前高频踩的坑至少少了三个。这篇文章不打算罗列一堆版本更新说明，我就把这三个坑的具体场景、当时的失败代码、以及TS5.7是怎么帮我挡住的，一条条讲清楚。如果你也在做AI应用开发、大模型应用开发，或者正在犹豫要不要从裸JS迁TS，这篇应该能给你一个相对实在的参考。

1. 为什么AI应用比普通Web应用更容易踩“类型坑”

1.1 一半业务逻辑藏在模型返回的JSON里

普通Web后端为什么不容易出这种问题？因为数据形状是被数据库Schema和ORM预先锁死的。你查出来的用户对象一定有字段，请求参数也大概率过了校验中间件，就算出问题，也知道去哪看。AI应用完全不是这个逻辑。你给模型一段提示词，希望它“严格按照JSON结构返回”，结果它给你返回一个长得相似、但字段缺一个、多两个、或者某个值变成null的结果。更麻烦的是，这还不是小概率事件，在长对话、多轮工具调用之后，结构漂移几乎是必然的。

很多AI应用的核心逻辑，其实就是“模型输出一个结构化的东西，我再拿这个结构去调用其他函数”。模型输出的结构，既没有数据库约束，也没有编译期约束。你脑子里觉得它该长什么样，代码里就按那个样子去写，但到运行那一刻它到底长什么样，只有天知道。裸JS对这种情况基本处于放任状态，写的时候顺畅，跑的时候一炸一个准。

1.2 裸JS不是不能用，而是“报错来得太晚”

我绝对不是想说裸JS一无是处。在项目早期、逻辑不复杂、只有一两个模型调用的时候，裸JS真的快，省去编译步骤，改完刷新就能看效果。但项目一旦进入“多个模型调用串起来、中间还有工具调用”的阶段，裸JS的短板就非常明显：它把所有该在编译期发现的问题，全部推迟到了运行期。

运行期报错带来的最大成本，不是修改那几行代码的时间，而是“你根本不知道系统里还有多少颗这样的雷”。有一次线上用户报告某个功能偶尔失败，我用日志反复排查，最后发现是模型返回的数组中有一个元素的字段名从title变成了heading。这种问题在裸JS里没有任何工具能提前提示你，你只能等真实用户踩到，再去数据库里翻记录。而TS6.7这种版本不是说能保证模型不出错，它是能把“你在代码里对一个不确定结构做的假设”提前暴露出来，让你在写代码的那一刻就重新审视：这个字段真的存在吗？这个数组真的不为空吗？

当然，如果你只是写一个几十行的脚本，裸JS完全没问题。但“AI应用开发”一旦涉及到智能体、多步推理、工具调用，代码的复杂度会快速逼近复杂后端项目。这时候，类型系统不是负担，而是一种廉价的“提前巡检”。

2. 坑1：模型返回的JSON“应该有字段”，字段偏偏没有

2.1 裸JS里的经典翻车现场

这是我最早遇到的一个坑。当时我做了一个内容分析工具，让模型从一段文本里提取文章列表。为了兼容模型偶尔改结构，我甚至写了很“聪明”的兼容逻辑：

const parsed = JSON.parse(responseText); const items = parsed.items ?? parsed.data?.items ?? []; const first = items[0]; console.log(first.title.toUpperCase());

你以为用了空数组兜底就安全了。但模型如果返回的是{"items": [{...}]}，那没问题；如果返回的是{"data": {"items": []}}，items就成了空数组，first就成了undefined，最后在.toUpperCase()那一行炸掉。裸JS的报错信息不会告诉你“这是模型输出问题”，只会告诉你Cannot read properties of undefined。你看着堆栈，根本分不清是模型问题、解析问题、还是自己代码逻辑问题。

这种代码我在裸JS时代写了一大堆。每处都做了防御，但防御本身也在增加复杂度，而且防御不到底——你永远可以在更深一层遇到漏网的情况。

2.2 用 unknown + 类型守卫，把脏数据堵在边界

迁到TS之后，我定的第一条规矩就是：所有模型输出在经过边界校验之前，一律当成unknown处理。unknown不是any，它逼你先把数据形状验证清楚，才能继续使用。配合自定义类型守卫，可以把“模型输出的字符串JSON”转换成“有明确形状的TS类型”。

比如我先定义期望的数据结构：

type Article = { id: string; title: string; tags: string[]; author?: string; };

然后写一个类型守卫函数，负责在程序的“边界”把关：

function isArticleList(value: unknown): value is Article[] { if (!Array.isArray(value)) return false; return value.every((item) => { if (typeof item !== 'object' || item === null) return false; const obj = item as Record<string, unknown>; return ( typeof obj.id === 'string' && typeof obj.title === 'string' && Array.isArray(obj.tags) && obj.tags.every((tag) => typeof tag === 'string') ); }); }

用法变成：

let data: unknown; try { data = JSON.parse(responseText); } catch { throw new Error('模型返回的不是合法JSON'); } if (!isArticleList(data)) { throw new Error('模型输出不符合 Article[] 约定'); } // 从这一行开始，data 被收窄为 Article[] const first = data[0]; console.log(first.title.toUpperCase());

这里最关键的是：从边界校验通过之后，后续所有代码都不需要再做各种“心里没底”的兼容判断。类型系统就是你的记忆，它会告诉你data已经是Article[]，里面的字段该有的都有。

2.3 TS5.7的never推断，为什么对这一步有实际价值

很多人在聊TS5.7的时候，喜欢拿“单类型参数在不变位置推断为never”这种底层特性出来说事。它听起来很抽象，但在AI应用的场景里，价值是实实在在的。

简单说，TS5.7改进了泛型推断的兜底策略。以前，当一个泛型类型参数只出现在不变位置（既要读又要写、既要当输入类型又要当输出类型），而推导又不够明确时，TypeScript很容易退化成any或者做出一个很奇怪的推断。any是一切问题的起点：一旦某个泛型工具函数返回了any，后面的类型检查全部失效，你等于又回到了裸JS。

TS5.7在无法收敛候选类型时会推断成never。never意味着“这个位置没有合理类型”，它会强制你在写代码的阶段去面对问题，而不是让错误悄悄溜过去。我在项目里写了好几个泛型解析器，比如从模型原始输出中提取某种结构化数据的工具函数。TS5.7之后，这类函数一旦类型参数没有绑定成功，IDE会立刻出现红色波浪线，逼我把泛型参数显式传清楚，而不是像以前那样，运行到线上才知道返回的是一个“比any更危险的半吊子类型”。

2.4 别用非空断言，那等于告诉编译器“我心里有数”

我还想补一个反模式：非空断言。

const title = parsed.data.items![0].title;

这种写法看着省事，实际是把错误信息亲手抹掉了。非空断言的意思是对编译器说“这里一定存在，我心里有数”，但模型输出恰恰是最容易让你“心里没数”的地方。我在裸JS时代吃过太多次这种亏。

正确的做法是：在边界做一次校验，后面全部走信任通道。TS的核心价值就是“把不确定性隔离在边界”，而不是让不确定性渗透到每一个字段访问上。运行时校验库可以用Zod或者Valibot，但不需要整个项目到处都用，只要在模型输出的入口处定义好Schema，然后在边界执行一次，效果就很好了。

3. 坑2：工具调用的函数签名，是最容易“隐身”的第三方契约

3.1 智能体工具调用是怎么把签名弄丢的

做AI智能体应用的人对“工具调用”一定不陌生。智能体的主流程大概是：模型根据用户问题，想到要调用某个工具，返回一个JSON格式的调用请求，比如{"name": "getWeather", "arguments": {"city": "北京"}}。然后你的代码解析这个请求，找到对应的handler函数，执行并把结果返回给模型。

问题出在这个“找对应handler函数”的过程上。裸JS时代，我维护着一份“工具注册表”，每个工具都有一份函数定义，还有一份发给模型的“工具描述JSON”，里面写着参数名、类型、必填项。这三份东西其实是同一个契约的三份拷贝，但没有任何编译期检查能把它们绑在一起。

有一次我修改了bookFlight的参数，把原来的date字段拆成了departDate和returnDate。我只改了handler函数和函数内部的逻辑，忘了同步发给模型的那份schema。结果模型继续按旧schema返回date字段，新代码又只认departDate，于是模型每次都说“抱歉，我需要确认一下日期”。排查了半天，最后发现根本不是模型变笨了，而是两边的契约已经严重不一致。

3.2 用 satisfies + 统一注册表锁死工具合同

TS里有个非常好用的语法叫satisfies，它不是TS5.7新增的，但和TS5.7的严格类型推断搭配起来，对AI工具调用这类场景非常友好。

核心思路是：用一个统一的ToolRegistry类型把“工具名称、参数类型、handler函数签名”绑定在一起，然后用satisfies去校验实际实现。任何地方不一致，在编译期就报错。

type ToolHandler<TArgs extends Record<string, unknown>, TResult = unknown> = { description: string; inputSchema: ZodType<TArgs>; handler: (args: TArgs) => Promise<TResult>; }; type ToolRegistry = { getWeather: ToolHandler<{ city: string; unit?: 'celsius' | 'fahrenheit' }>; bookFlight: ToolHandler<{ from: string; to: string; date: string }>; };

注册表实现：

const tools = { getWeather: { description: '查询指定城市天气', inputSchema: z.object({ city: z.string(), unit: z.enum(['celsius', 'fahrenheit']).optional() }), handler: async (args) => { // args 已经被推断为 { city: string; unit?: 'celsius' | 'fahrenheit' } return fetchWeather(args.city, args.unit); } }, bookFlight: { description: '预订航班', inputSchema: z.object({ from: z.string(), to: z.string(), date: z.string() }), handler: async (args) => { // 这里如果漏掉 date，编译器直接报错 return bookFlightTicket(args.from, args.to, args.date); } } } satisfies ToolRegistry;

这样写的好处是：当你删了bookFlight的date字段、改成departDate，ToolRegistry类型里就会有一处不匹配。如果底层实现没同步改，编译器会指着handler说“你这里参数不对”。如果改完了handler但忘了同步发给模型的schema，至少不会出现“代码自己跟自己都不知道签名是什么”的尴尬状态。当然，运行时依然要用Zod对模型传来的arguments再校验一遍，但编译期这层锁，已经帮我挡掉了大量低级错误。

3.3 TS5.7的never推断，在工具定义里带来的“强制显式”

我在迁移过程中写过不少泛型封装，比如想写一个通用的defineTool函数，让每个工具的注册代码更简洁。这类封装最容易出现的问题就是：泛型类型参数没有绑定好，结果TypeScript默默推断成any，然后整个工具链路的类型安全瞬间崩盘。

function defineTool<TArgs extends Record<string, unknown>>( config: { name: string; inputSchema: ZodType<TArgs>; handler: (args: TArgs) => Promise<unknown>; } ) { return { name: config.name, zodSchema: config.inputSchema, run: config.handler }; }

如果某个工具在调用defineTool时没把类型参数显式传进去，旧版本TypeScript可能在某个边界退化成any，你的args就变成了隐形的“裸JS”。TS5.7把这种场景的失败模式改成了never：它会在推断不出的时候，把类型位置标记成never，让你立刻意识到“这里缺了一个明确类型”。这种强制显式，对需要长期维护的智能体项目来说，非常宝贵。

3.4 把LLM Function Declarations变成单一数据源

既然说到工具调用，再分享一个从这次迁移中摸索出来的做法：不要同时维护“TS类型、Zod Schema、LLM Function Declarations”三份独立数据。现代AI应用开发里，最好让它们从同一个数据源推导。

我最简单的做法是，用Zod Schema作为单一数据源，然后通过z.infer拿到TS类型，再通过Zod Schema的解析逻辑生成一份给模型看的工具描述。这样模型期望的参数结构、代码实际接收的参数结构、运行时校验结构，三边完全一致。裸JS时代那种“模型按旧schema传参数、代码按新schema读参数”的错位，从根本上被消灭了。

4. 坑3：异步编排里的“空数组、未初始化、Promise传导”

4.1 Promise.all 被单个模型调用失败整段拖垮

AI应用里最常用的异步编排是Promise.all。比如要给一批任务分别调用模型，然后把结果汇总起来。裸JS写法往往长这样：

const results = await Promise.all( tasks.map(async (task) => { if (task.disabled) return; return runAgent(task); }) ); results.forEach((r) => { console.log(r.resultId); });

这里的问题非常隐蔽：task.disabled时，回调函数直接return，返回的是一个undefined。Promise.all不会报错，它会把undefined塞进结果数组。然后你拿r.resultId去访问，运行期直接炸。裸JS里，你看到的报错是Cannot read property 'resultId' of undefined，但根本不知道是哪个任务出的问题。

TS迁过来之后，同一段代码在编译期就会提示你：results的类型是(AgentResult | undefined)[]，r可能是undefined。就算你没仔细看类型，IDE的红色波浪线也会逼你处理这个潜在空值。

我当时把这段代码改了：

const activeTasks = tasks.filter((task) => !task.disabled); const results = await Promise.all(activeTasks.map((task) => runAgent(task))); results.forEach((r) => { console.log(r.resultId); });

把“过滤”和“执行”拆开，结果数组里再也不会混进undefined。这算是个很小的改动，但让我少排查了很多次“幽灵空值”。

4.2 TS5.7的未初始化变量检查，帮我抓住“晚初始化”

AI应用的状态管理经常跨异步回调。用户可能先发起一个请求，然后在某个回调里设置状态，之后再在另一个异步函数里读取。这种“说不定已经初始化，说不定还没初始化”的变量，简直是运行期错误的温床。

TS5.7加强了对未初始化变量的检查。它能在你“读取一个可能还没赋值的变量”时，直接给出编译期警告。举个实际场景：

let currentContext: string[]; async function handleUserMessage(userInput: string) { if (!sessionExists()) { return; } currentContext = loadSessionContext(); const reply = await callModel(currentContext, userInput); return reply; }

这个例子看起来没问题，但如果在某个分支里忘了调loadSessionContext()就直接给callModel传currentContext，5.7会把“变量在赋值前被使用”的局面直接标出来。这在裸JS里根本不可能提前发现。AI应用里，这种状态变量往往分散在好几个模块里，靠人脑记忆谁先赋值谁后使用，早晚出问题。

4.3 用判别联合状态机管理智能体生命周期

顺着上面的问题，我后来用TypeScript的判别联合类型，给智能体的运行状态画了一个明确的状态机。这个设计不是为了炫技，而是为了让“当前智能体到底处于什么阶段”这个问题有标准答案。

type AgentState = | { phase: 'idle' } | { phase: 'collecting'; messages: Message[]; pendingTool?: ToolCall } | { phase: 'executing'; toolName: string; startedAt: number } | { phase: 'done'; runId: string; tokenUsage: TokenUsage } | { phase: 'error'; code: ErrorCode; retryCount: number };

这个联合类型里，每一个状态都带了自己该有的数据。executing一定带startedAt，error一定带retryCount。如果你想在idle状态下访问tokenUsage，编译期就会报错。等于编译器强制你把状态转换的逻辑理顺。

配合一个transition函数，非法状态迁移也能在编译期被拦截：

function transition(state: AgentState, next: AgentState): AgentState { // 在这里定义哪些迁移是合法的 return next; }

这套东西不是银弹，但对于需要重试、需要记录token消耗、需要在多轮工具调用里维护上下文的智能体应用来说，效果立竿见影。裸JS里那种“用一个字段表示阶段，然后再写十几个if判断该显示什么操作”的做法，到了TS里基本可以被这种类型状态机替代得干干净净。

5. 迁移后的收益曲线，以及我建议的顺序

5.1 改造前后的一组直观对比

我把这个项目从裸JS迁到TS5.7之后，没有做什么花哨的架构升级，只是把上面三条路径打通了：模型输出入口类型校验、工具调用注册表类型化、异步编排和状态管理用类型约束。单纯从报错数量上看，我自己的项目里，运行期因为“读取undefined字段”导致的错误，占全部日志的比例明显下降。原来一周可能要处理好几起这类问题，迁移后的一个月里基本绝迹。

我整理了一个粗略对比表：

这张表反应的是我自己的体感，不一定所有人都会得出相同结论，但对正在往AI大模型应用开发这个方向走的人来说，方向应该是一致的：类型系统不是在限制你，而是在帮你把“模型不可控”这个老问题，收窄到一个可以管理的范围内。

5.2 渐进迁移的四个阶段

很多人一想到迁移到TS，就觉得是一个大工程，要重写所有文件。其实流程可以是渐进的。

第一阶段：先把项目交给TypeScript编译器管理。在tsconfig.json里打开allowJs: true、checkJs: false，让tsc --noEmit能跑通所有JS文件，但暂时不检查类型。这一步只是让TS开始接管项目结构。

第二阶段：选中AI应用中最核心的“边界文件”，比如调用模型、解析模型输出、处理工具调用的那几个文件，在文件头部加上// @ts-check，并补齐必要类型。这就是最小可用闭环。

第三阶段：按目录逐步打开strict模式，把TS 5.7新增的编译选项用起来。比如--rewriteRelativeImportExtensions这类基于ESM的选项，对Node端项目迁移非常友好；如果你用了路径映射，TS5.7对“目录导入”的解析也比旧版本更省心。

第四阶段：把临时用的any逐步清除。我不建议一步到位禁止所有any，但也不建议留着超过一个迭代。每个any都是一块重新裸奔的区域，会把你辛苦建立起来的类型边界重新撕开。

5.3 三条落地建议

最后给三条比较实操的建议，都是我踩过一遍之后的体会。

第一，所有模型输出入口必须统一过校验。不管后端用什么模型，返回结构有多简单，都要在边界做一次类型守卫或者Zod校验。宁可在这里多写几行，也不要让未知结构在项目里四处流窜。

第二，工具调用注册表一定要类型化。工具函数、Zod Schema、LLM Function Declarations三边要从同一数据源推导。裸JS时代那种“改函数忘改schema”的问题，在类型化注册表里基本不存在。

第三，CI里一定要跑tsc --noEmit。开发环境编辑器里的红色波浪线只是第一道防线，CI才是真正的门禁。只靠本地IDE，很容易出现“我本地能跑”但别人拉下来编译失败的情况。

如果你也正在写AI应用，或者在准备AI应用开发相关的面试，可以试试从这三个点入手。工具调用的参数结构、模型输出的校验、异步状态机的建模，几乎每次都有人问。把这些用TS 5.7的类型能力框住之后，你会发现，AI应用开发并没有想象中那么“玄学”，大部分坑都是可以提前用代码挡住的。