# localhost 上跑通的 React 演示，只完成了一半

> 六个步骤，把客户演示从没装 Node 的电脑做到类型检查通过、API 密钥不进包的干净构建。

原文: https://fdetimes.net/zh/guides/react-typescript-client-demo-six-steps/

周二，客户问：“周五能让我的团队试一下吗？”基于内部文档回答问题的后端已经能用，但客户不会去看 JSON。他们需要一个文本框、一个按钮，以及显示在屏幕上的答案。客户给你的工作电脑什么都没装，连 Node 都没有。

前线部署工程师（FDE）经常遇到这种情况。这时需要的不是高深的 React 功夫，而是在几个小时内从零做到干净的构建，并且下周同事能直接接手。下面六个步骤以这样一个例子为线索，从第一条命令一直走到 `dist` 文件夹。

## 为什么用 Vite，而不是框架？

React 官方文档推荐用框架来创建新应用。文档也坦率说明了自行搭建的代价：灵活性更高，但路由、数据获取等常见模式都要自己选工具。

对于只有一个页面的演示，这个代价几乎为零，因为现阶段既不需要路由，也不需要复杂的数据获取策略。Vite 提供的脚手架轻量、启动快。如果演示日后发展成多页面产品，那时再重新考虑框架也不迟。

## 第 1 步：先装对 Node，再敲别的命令

Vite 要求 Node.js 20.19+ 或 22.12+。在空白机器上，安装 22.12 或更高版本，可以用官方安装包，如果客户的机器允许，也可以用 nvm 之类的版本管理工具。然后检查：

```bash
node -v
npm -v
```

如果 `node -v` 输出的版本低于要求，立即停下来修好。Node 版本错误如果在后面的步骤才暴露，往往看起来像 Vite 的错误，你可能会花一个下午排查错误的方向。

## 第 2 步：一条命令搭脚手架，一条命令运行

Vite 用 `npm create vite@latest` 创建项目。React 加 TypeScript 的模板是 `react-ts`（另有 `react-compiler-ts`）：

```bash
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`。这个文件是后端与界面之间的契约：

```ts
export type Status = "idle" | "loading" | "done" | "error";

export type Answer = {
  text: string;
  sources: string[];
};
```

React 文档指出，声明好的 props 类型既能检查正确性，也是直接显示在编辑器里的文档。对 FDE 来说，第二个好处同样重要：接手的人打开文件，不用调用 API 就知道它返回什么。

## 第 4 步：所有 API 调用集中在一处

创建 `src/api.ts`。所有网络相关代码都放在这里，周四客户改了后端地址，你只需改一行：

```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` 文件：

```bash
VITE_API_URL=http://localhost:8000
```

有一个细节最为关键：`VITE_` 变量会直接打包进浏览器中运行的代码，Vite 文档明确写道，这些变量不能包含 API 密钥等敏感信息。模型的密钥、客户系统的密钥都应放在后端，UI 只知道地址。

**要点:** 前端代码里的任何内容，打开浏览器的人都能看到。

## 第 5 步：把 API 接到界面上

到这一步才轮到 `src/App.tsx`，模板已经创建好了这个文件。包含 JSX 的文件必须使用 `.tsx` 扩展名，所以不要把它改成 `.ts`。用下面的代码替换文件内容：

```tsx
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`：

```bash
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` 文件夹链接。

**本周动手试试:**

- 在一台没有 Node 的机器（或用户账户）上，计时完成全部六个步骤，直到 dist 文件夹出现，记下哪一步耗时最长。
- 在 App.tsx 里故意写错 status: "loadng"，看开发服务器会不会报错；然后运行 npx tsc --noEmit，调整命令，直到它真正查出这个错误。
- 构建完成后，在 dist 文件夹中搜索与任一 VITE_ 变量取值相同的字符串，亲自确认打包产物里有什么。

## 信源

- [Getting Started | Vite](https://vite.dev/guide/)

- [Start a New React Project – React](https://react.dev/learn/start-a-new-react-project)

- [Using TypeScript – React](https://react.dev/learn/typescript)

- [Features | Vite](https://vite.dev/guide/features)

- [Deploying a Static Site | Vite](https://vite.dev/guide/static-deploy)

- [Env Variables and Modes | Vite](https://vite.dev/guide/env-and-mode)
