FDE Times 数据在招 FDE 职位 924▲33 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 80在招公司 196支持远程 25%美国薪资中位数 $200k招聘最多 Databricks 107
ENVI

前线部署工程师(FDE)的专业媒体

技能指南 · 指南

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

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

分享微博

要点速览

  • Vite 需要 Node.js 20.19+ 或 22.12+。动手之前先运行 node -v。
  • Vite 只转译 TypeScript,不做类型检查。构建到 dist 之前先运行 tsc --noEmit,并故意埋一个错误,确认命令真能查出来。
  • 所有 VITE_ 变量都会打包进客户端代码,API 密钥必须放在后端。
示意图由三个以箭头相连的方块组成:浏览器只持有 VITE_API_URL 变量;后端以橙色突出显示,因为它持有 API 密钥;最后是客户的系统。浏览器方块下方注明:任何打开浏览器的人都能读到。
VITE_ 变量会直接打包进浏览器中运行的代码。因此演示前端只应知道后端地址,模型的密钥或客户系统的密钥必须留在服务器上。来源:Vite 文档,见正文引用。

周二,客户问:“周五能让我的团队试一下吗?”基于内部文档回答问题的后端已经能用,但客户不会去看 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 文件夹链接。

这篇文章对你有帮助吗?

6 个信源
路线图上的下一篇 · 阶段 2: 全栈工程能力Agent 重试一次 API,同一笔订单退了两次款超时、有节制的重试和每个操作固定一个幂等键,约 80 行 TypeScript,今天就能用到项目里。