localhost 上跑通的 React 演示,只完成了一半
六个步骤,把客户演示从没装 Node 的电脑做到类型检查通过、API 密钥不进包的干净构建。
要点速览
- Vite 需要 Node.js 20.19+ 或 22.12+。动手之前先运行 node -v。
- Vite 只转译 TypeScript,不做类型检查。构建到 dist 之前先运行 tsc --noEmit,并故意埋一个错误,确认命令真能查出来。
- 所有 VITE_ 变量都会打包进客户端代码,API 密钥必须放在后端。
周二,客户问:“周五能让我的团队试一下吗?”基于内部文档回答问题的后端已经能用,但客户不会去看 JSON。他们需要一个文本框、一个按钮,以及显示在屏幕上的答案。客户给你的工作电脑什么都没装,连 Node 都没有。
前线部署工程师(FDE)经常遇到这种情况。这时需要的不是高深的 React 功夫,而是在几个小时内从零做到干净的构建,并且下周同事能直接接手。下面六个步骤以这样一个例子为线索,从第一条命令一直走到 dist 文件夹。
为什么用 Vite,而不是框架?
React 官方文档推荐用框架来创建新应用。文档也坦率说明了自行搭建的代价:灵活性更高,但路由、数据获取等常见模式都要自己选工具。
对于只有一个页面的演示,这个代价几乎为零,因为现阶段既不需要路由,也不需要复杂的数据获取策略。Vite 提供的脚手架轻量、启动快。如果演示日后发展成多页面产品,那时再重新考虑框架也不迟。
第 1 步:先装对 Node,再敲别的命令
Vite 要求 Node.js 20.19+ 或 22.12+。在空白机器上,安装 22.12 或更高版本,可以用官方安装包,如果客户的机器允许,也可以用 nvm 之类的版本管理工具。然后检查:
node -v
npm -v
如果 node -v 输出的版本低于要求,立即停下来修好。Node 版本错误如果在后面的步骤才暴露,往往看起来像 Vite 的错误,你可能会花一个下午排查错误的方向。
第 2 步:一条命令搭脚手架,一条命令运行
Vite 用 npm create vite@latest 创建项目。React 加 TypeScript 的模板是 react-ts(另有 react-compiler-ts):
npm create vite@latest client-demo -- --template react-ts
cd client-demo
npm install
npm run dev
默认的 dev 脚本就是 vite,它会在 localhost:5173 启动开发服务器。示例页面出现,基础设施就搭好了。如果客户已有一个用 JavaScript 写的 React 项目,不必推倒重来,补上类型定义即可:npm install --save-dev @types/react @types/react-dom。
第 3 步:先写数据类型,再写 UI
动界面之前,先创建 src/types.ts。这个文件是后端与界面之间的契约:
export type Status = "idle" | "loading" | "done" | "error";
export type Answer = {
text: string;
sources: string[];
};
React 文档指出,声明好的 props 类型既能检查正确性,也是直接显示在编辑器里的文档。对 FDE 来说,第二个好处同样重要:接手的人打开文件,不用调用 API 就知道它返回什么。
第 4 步:所有 API 调用集中在一处
创建 src/api.ts。所有网络相关代码都放在这里,周四客户改了后端地址,你只需改一行:
import type { Answer } from "./types";
// 只是后端地址,不是密钥
const API_URL = import.meta.env.VITE_API_URL;
export async function readAnswer(question: string) {
const res = await fetch(`${API_URL}/answer`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ question }),
});
if (!res.ok) throw new Error(`API 返回 ${res.status}`);
return (await res.json()) as Answer;
}
(注释的意思是:“只是后端地址,不是密钥。”错误信息为“API 返回”加上状态码。)
项目根目录下的 .env 文件:
VITE_API_URL=http://localhost:8000
有一个细节最为关键:VITE_ 变量会直接打包进浏览器中运行的代码,Vite 文档明确写道,这些变量不能包含 API 密钥等敏感信息。模型的密钥、客户系统的密钥都应放在后端,UI 只知道地址。
第 5 步:把 API 接到界面上
到这一步才轮到 src/App.tsx,模板已经创建好了这个文件。包含 JSX 的文件必须使用 .tsx 扩展名,所以不要把它改成 .ts。用下面的代码替换文件内容:
import { useState } from "react";
import type { FormEvent } from "react";
import { readAnswer } from "./api";
import type { Answer, Status } from "./types";
type UiState = { status: Status; answer: Answer | null };
const initial: UiState = { status: "idle", answer: null };
export default function App() {
const [ui, setUi] = useState(initial);
async function handleSubmit(e: FormEvent) {
e.preventDefault();
const form = new FormData(e.currentTarget as HTMLFormElement);
const question = String(form.get("question") ?? "");
setUi({ status: "loading", answer: null });
try {
const answer = await readAnswer(question);
setUi({ status: "done", answer });
} catch {
setUi({ status: "error", answer: null });
}
}
return (
<form onSubmit={handleSubmit}>
<textarea name="question" rows={4} />
<button disabled={ui.status === "loading"}>提问</button>
{ui.status === "error" && <p>无法连接 API,请重试。</p>}
{ui.answer && <p>{ui.answer.text}</p>}
</form>
);
}
(按钮文字意为“提问”;错误提示意为“无法连接 API,请重试”。)
注意 useState(initial) 这一行。这个 hook 会根据初始值推断类型。如果直接写 useState("idle"),TypeScript 推断出的类型是 string,"loadng" 这样的拼写错误就会漏过去。如果写 useState(null),类型就是 null,答案根本赋不进去。
最简洁的办法是给 hook 一个本身已带类型的初始值。initial 声明为 UiState,所以 status 只接受联合类型中的四个值,answer 只接受 null 或 Answer。如果你更喜欢拆成几个独立的 state,标准做法是把 Status 直接作为类型参数传给 useState。
把两部分状态放进同一个对象还有一个好处:不会出现状态已是“error”、屏幕上却还留着旧答案的情况。保存文件,回到 localhost:5173,输入问题并点击。后端在运行,答案就会出现;关掉后端,错误提示就会出现。客户两种情况都会试到,所以你也必须都试一遍。
第 6 步:开发服务器能跑,不等于代码正确
这是最大的陷阱。Vite 只转译 TypeScript 文件,不检查类型。开发服务器照样会提供满是类型错误的文件,直到客户恰好点进出错的分支,你才会发现。正因如此,Vite 文档建议在构建生产版本时运行 tsc --noEmit:
npx tsc --noEmit
npm run build
不要因为类型检查命令什么都没报就信任它,要证明它有效:在给 status 赋值的地方写上 "loadng",再运行一次。如果命令依然沉默,很可能它根本没检查到 UI 代码。在有多个 tsconfig 文件的项目里,用 -p 参数直接指向覆盖 src 代码的那个配置,直到这个故意埋下的错误被报出来。
接着打开 package.json,看 build 脚本是否在 vite build 之前执行类型检查。如果没有,就加上,免得团队里有人忘记。构建产物默认输出到 dist 文件夹:一组静态文件,放到 Web 服务器上,客户用浏览器就能打开。
毁掉周五演示的几个错误
最常见的错误是把开发服务器当成证据。在 localhost 上跑起来的页面,只能说明浏览器能运行这段代码,不能说明类型正确。紧随其后的,是信任一条报告“没问题”、却从未被验证能查出任何错误的类型检查命令。
最危险的错误是图省事把密钥放进 VITE_ 变量,理由是“只是个演示”。演示包会通过邮件和群聊转来转去,密钥也跟着一起流传。只要犯一次,就足以失去客户安全团队的信任。
还有两个小错误会浪费好几个小时:在 .ts 文件里写 JSX;对有多种取值的状态,让 useState 从一个裸字符串或 null 推断类型。只要给 TypeScript 机会,这两个错误它都能查出来。
这项技能在简历上怎么体现?
阅读 FDE 岗位描述时,留意“build prototypes”“customer-facing demos”“rapid iteration”这类表述。如果出现了,这六个步骤正是你应该能够展示的能力,而展示成果比罗列技术更有说服力。
简历上不要写“精通 React、TypeScript”,而是写一句有结果的话:在一次工作中,从空白机器开始完成文档问答演示并产出生产构建,API 层独立,更换后端无需改动 UI,密钥保留在服务器端。一个公开仓库,结构正好是 types.ts、api.ts、App.tsx,比任何形容词都更能说明你的能力。
下次客户再问“周五能试一下吗?”,正确的回答不是“可以”,而是周四下午发过去的一个 dist 文件夹链接。
这篇文章对你有帮助吗?
感谢你的反馈!