# FDE 应自己掌握界面代码，而不是装一个 UI 库

> shadcn/ui 把组件代码直接复制进仓库，管理后台想怎么改就怎么改，不必等任何人。

原文: https://fdetimes.net/zh/tools/fde-own-ui-code-shadcn-ui/

设想这样一个场景：周一和客户见面，周五就要演示一个处理订单的智能体。智能体能跑通，但客户的操作人员需要一个界面来审核它的输出，而项目里没有设计师。

这时最合适的工具，是能让你在自己仓库里改动界面每一行代码的工具。一个好看但封闭的 UI 库，想改点什么都得绕路，偏偏会在你最需要提速的那一周拖慢你。

shadcn/ui 走的就是这条路。它的 GitHub 仓库称其为可组合、注重无障碍的组件。官方文档说得更直接：它不是一个组件库，而是一种构建你自己组件库的方式。

对前线部署工程师（FDE）来说，这个区别不只是措辞问题。每次演示都会遇到客户想改个小细节的时刻。修改自己掌握的文件，远比想办法改动别人维护的包要快。

## 组件代码就在你的仓库里

项目把这条原则称为 Open Code。文档说得很干脆：最上层的组件代码由你直接修改，想改按钮，就打开按钮的代码去改。客户希望状态列给逾期订单显示红色徽标时，你不用覆盖别人的样式，也不用等 issue 的回复。

Vercel Academy 总结得很到位：传统组件库建立的是依赖关系，shadcn/ui 建立的是所有权关系。样式基于 Tailwind CSS。Tailwind CSS 4.0 于 2025 年 1 月 22 日发布，最大的变化是把项目配置从 JavaScript 移到了 CSS。

## 订单审核演示：一步步来

回到订单审核界面。假设你从一个使用 React 和 TypeScript 的 Vite 项目起步。在 Vite 上使用 Tailwind v4 需要两样东西：`@tailwindcss/vite` 插件，以及 CSS 文件里的一行 import。之后，shadcn CLI 的 `add` 命令会把组件及其依赖加进项目。

```bash
npm install tailwindcss @tailwindcss/vite
npm install -D @types/node   # 让 vite.config 可以使用 path 模块
# 在 src/index.css 中，把全部内容替换为：@import "tailwindcss";
```

光装包还不够，插件必须在 `vite.config.ts` 里注册。顺便声明一个指向 `src` 目录的 `@` 别名，因为组件代码都以 `@/components/ui/button` 这样的形式导入：

```ts
// vite.config.ts
import path from "path"
import react from "@vitejs/plugin-react"
import tailwindcss from "@tailwindcss/vite"
import { defineConfig } from "vite"

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: { alias: { "@": path.resolve(__dirname, "./src") } },
})
```

TypeScript 也得认识这个别名。在 `tsconfig.json` 中（如果模板拆分了文件，`tsconfig.app.json` 也要改），给 `compilerOptions` 加两行：`"baseUrl": "."` 和 `"paths": { "@/*": ["./src/*"] }`。漏了这一步，`init` 很难顺利运行，`@/...` 导入也会报错，赶工时很容易卡在这里。

```bash
npx shadcn@latest init
npx shadcn@latest add sidebar table button
npm install @tanstack/react-table
```

由于 Tailwind v4 在 CSS 里配置，换成客户品牌色要改的是 CSS 文件，而不是 JavaScript 文件。能快速换色很值。客户管理层在界面上看到自家品牌色时，更容易把这个工具看作公司自己的东西，而不是外人做的原型。

`add sidebar` 则会给你一个导航栏，文档称它可组合、可换主题、可定制：左边菜单，右边内容，就是所有管理后台熟悉的框架。

最费功夫的是订单表格。shadcn/ui 的 Data Table 不是预先打包好的表格。文档没有提供现成组件，而是给出一份指南，教你在 TanStack Table 上自己组装表格。

**要点:** 做演示时，能改动界面每一行代码的权利，比一个漂亮的组件库更有价值。

这种组装方式其实很适合在客户现场工作。假设智能体处理了 200 个订单。操作人员只需要按“待审核”状态筛选，按创建日期排序以先看最早的订单，再点击某一行查看智能体的决定。

你只定义这几列，只加一个排序和一个筛选，别的都不要。下面的示例很精简，但导入语句齐全；用 `Table` 组件渲染表格的部分，按指南自己补上：

```tsx
// columns.tsx
import { ColumnDef } from "@tanstack/react-table"
import { Button } from "@/components/ui/button"

export type Order = { id: string; status: "needs_review" | "approved"; createdAt: string }

export const columns: ColumnDef<Order>[] = [
  { accessorKey: "id", header: "订单 ID" },
  { accessorKey: "status", header: "状态" },
  {
    accessorKey: "createdAt",
    header: ({ column }) => (
      <Button variant="ghost"
        onClick={() => column.toggleSorting(column.getIsSorted() === "asc")}>
        创建时间
      </Button>
    ),
  },
]
```

```tsx
// data-table.tsx（示例：省略了渲染表格的 JSX）
import { useState } from "react"
import {
  useReactTable,
  getCoreRowModel,
  getSortedRowModel,
  getFilteredRowModel,
  SortingState,
  ColumnFiltersState,
} from "@tanstack/react-table"
import { columns, Order } from "./columns"

export function OrdersTable({ data }: { data: Order[] }) {
  const [sorting, setSorting] = useState<SortingState>([])
  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([])

  const table = useReactTable({
    data, columns,
    getCoreRowModel: getCoreRowModel(),
    getSortedRowModel: getSortedRowModel(),
    getFilteredRowModel: getFilteredRowModel(),
    onSortingChange: setSorting,
    onColumnFiltersChange: setColumnFilters,
    state: { sorting, columnFilters },
  })
  // “待审核”按钮：table.getColumn("status")?.setFilterValue("needs_review")
  // ……渲染 table.getHeaderGroups() 和 table.getRowModel().rows
}
```

## 自己掌握代码的代价

缺点就藏在优点里。Vercel Academy 把代价讲得很清楚：你失去了自动更新和自动安全补丁。据 PkgPulse 介绍，要更新某个组件，得重新运行它的生成命令，而这条命令会覆盖文件，不先做比对的话，你的修改可能就丢了。

也别以为一切都归你所有。PkgPulse 指出，复制过来的组件仍然依赖 node_modules 里的 Radix 包。你掌握的是最上层，下面那层依旧是普通依赖。

无障碍同样需要留意。这些组件在设计时考虑了无障碍，但一旦为了迎合客户改了标记，就没人替你重新检查。演示阶段可以接受；如果这个界面即将成为正式上线的内部工具，交付前要和客户商定由谁维护界面代码。

生态还在演进。2026 年 8 月的更新日志提到，GitHub registry 现已支持私有仓库，团队可以把定制过的内部组件集中放在一个私有位置。对同时运行多个项目的客户，交付时值得提一下。

最后一个局限是 Data Table。因为要自己组装，如果你刚接触 TanStack Table，这里最耗时间。签合同之前就把它学会，别拖到周四晚上。

## 先学什么，简历上怎么写

合理的顺序是先学 Tailwind，因为组件构建在它之上，同时学会在 Vite 里配置插件和别名。然后学 `init` 和 `add` 命令，把大部分时间花在 TanStack Table 上，这是唯一必须真正弄懂、不能只复制来用的部分。

至于职业发展，一个能用的管理后台，招聘经理可以自己点开试，比任何描述技能的句子都更有说服力。简历上别写含糊的“熟悉 React”，而是写类似“搭建了审核智能体输出的界面，支持基于真实数据的排序和筛选”，并附上仓库链接。

你不需要成为设计师。值得证明的是：客户问“能给我看看吗？”的时候，你能当场打开一个界面给他们看。

**本周动手试试:**

- 新建一个 Vite React 项目，安装 tailwindcss 和 @tailwindcss/vite，在 vite.config 和 tsconfig 中注册插件和 @ 别名，然后运行 init 并执行 add sidebar
- 找一个几百行的公开 CSV 文件，组装一个按日期排序、按状态筛选的 Data Table，再把仓库推到 GitHub 作为作品集
- 把 CSS 文件里的主题色改成任意一家公司的品牌色，练习为客户调整界面

## 信源

- [Introduction - shadcn/ui](https://ui.shadcn.com/docs)

- [shadcn - shadcn/ui](https://ui.shadcn.com/docs/cli)

- [GitHub - shadcn-ui/ui: Composable, accessible components with thoughtful defaults.](https://github.com/shadcn-ui/ui)

- [Data Table](https://ui.shadcn.com/docs/components/data-table)

- [Sidebar - shadcn/ui](https://ui.shadcn.com/docs/components/sidebar)

- [Changelog - shadcn/ui](https://ui.shadcn.com/docs/changelog)

- [Tailwind CSS v4.0 - Tailwind CSS](https://tailwindcss.com/blog/tailwindcss-v4)

- [Installing Tailwind CSS with Vite - Tailwind CSS](https://tailwindcss.com/docs/installation)

- [Why shadcn/ui is Different (Vercel Academy)](https://vercel.com/academy/shadcn-ui/why-shadcn-ui-is-different)

- [shadcn/ui vs Radix UI: Component Library vs 2026 (PkgPulse Guides)](https://www.pkgpulse.com/guides/shadcn-ui-vs-radix-ui-component-library)
