Strapi 设计系统实战：用 yarn link 在 Strapi Monorepo 中本地开发 @strapi/design-system

Strapi 的 Admin Panel 界面完全构建在独立维护的 @strapi/design-system 之上，但设计系统源码并不在 Strapi monorepo 内，而是在单独的仓库中发布。本文围绕仓库中的贡献者指南 02-working-with-the-design-system.md，讲解如何把本地设计系统仓库链接进 Strapi monorepo 进行联调开发、如何在 examples/getstarted 中验证改动生效、如何回退到已发布版本，并结合仓库依赖配置与类型声明，说明设计系统在 Strapi 前端代码中的真实使用位置。

设计系统与 Strapi Monorepo 的关系

Strapi 管理后台（Admin Panel）的 UI 组件库是 @strapi/design-system，它和图标库 @strapi/icons 一样以独立 npm 包的形式发布，Strapi 仓库通过依赖版本锁定的方式引用它们。从 packages/core/admin/package.json 可以看到核心引用：

"dependencies": {
  "@strapi/design-system": "2.2.4",
  "@strapi/icons": "2.2.4",
  ...
}

也就是说，monorepo 内任何涉及 Admin UI 的代码，其组件（如 Box、Flex、IconButton、Form、ConfirmDialog 等）都来自外部包。@strapi/design-system 并非仅被 admin 包使用，仓库中依赖它的前端包覆盖面很广，包括：

• packages/core/admin、packages/core/content-manager、packages/core/content-type-builder
• packages/core/content-releases、packages/core/review-workflows、packages/core/email、packages/core/upload
• packages/plugins/users-permissions、packages/plugins/i18n、packages/plugins/graphql、packages/plugins/cloud 等

因此，一旦把本地设计系统链接进来，改动会直接影响所有上述包在开发构建中的表现。04-fe-coding-guidelines.mdx 中的 A11y 章节也印证了这一点：CMS 中构建 UI 通常都通过 design-system 完成，大部分无障碍工作由设计系统层面承担。

主题类型层面同样与设计系统强耦合。packages/core/admin/admin/custom.d.ts 中：

import { type StrapiTheme } from '@strapi/design-system';

declare module 'styled-components' {
  export interface DefaultTheme extends StrapiTheme {}
}

styled-components 的 DefaultTheme 直接继承设计系统导出的 StrapiTheme，这意味着设计系统的主题 token（颜色、字号、间距等）就是整个 Admin 代码中 useTheme() 类型的来源。本地替换设计系统版本时，如果主题字段有增删，这里会出现类型层面的连锁反应——这也是本地联调的主要场景之一。

链接本地设计系统的完整步骤

以下流程完整继承自 02-working-with-the-design-system.md，适用于 Strapi monorepo 的本地开发环境（基于 yarn workspaces，仓库根 package.json 的 workspaces 字段将 packages/*、packages/*/*、examples/* 都纳入了工作区）。

第 1 步：构建本地设计系统

先在设计系统仓库中执行构建，生成可供消费的 bundle：

# 在你的 strapi-design-system 本地副本中
yarn build

必须先生成 bundle 再链接，因为 Strapi 侧消费的是设计系统的构建产物（main/module 入口指向 dist 产物），而不是其 TypeScript 源码。

第 2 步：在 Strapi monorepo 中执行 yarn link

切换到 Strapi monorepo 根目录，执行：

yarn link -r ../<relative-path-to-strapi-design-system>

yarn link -r（即 yarn link --recursive）会递归遍历当前 monorepo 的所有工作区包，把每个包中声明的 @strapi/design-system 依赖指向你的本地副本。由于根 package.json 的 workspaces 已覆盖全部 packages 与 examples，这一条命令即可让所有引用设计系统的子包同时切换到本地版本，而无需逐个包操作。

-r 参数对路径的解析以命令执行位置为基准，所以 ../<relative-path-to-strapi-design-system> 是相对 monorepo 根目录的相对路径。如果设计系统仓库放在 monorepo 同级目录（这是官方推荐的目录布局），路径形如 ../strapi-design-system。

第 3 步：在 examples/getstarted 中验证

指南给出的验证方式是运行 examples/getstarted 的构建：

cd examples/getstarted
yarn build

examples/getstarted 是一个完整的 Strapi 示例应用，其 package.json 中的构建脚本为 strapi build，构建过程会打包整个 Admin Panel 前端。若链接成功，该构建消费的就是你本地修改过的设计系统 bundle——可以直接通过产物或本地开发运行观察 UI 变化来确认改动生效。

第 4 步：用 yarn unlink 回退到发布版本

开发完成、需要恢复 npm 上发布的 @strapi/design-system（当前锁定的 2.2.4 版本）时执行：

yarn unlink ../<relative-path-to-strapi-design-system>

yarn unlink 会移除递归链接，各包重新解析回 package.json 中声明的固定版本号，node_modules 恢复为 registry 版本。

仓库中相关机制的补充说明

理解这套流程，可以对照仓库中的几处实现细节：

1. 仓库自带的 link 脚本不覆盖本场景。scripts/link.js 是用于把 monorepo 内部的包全部 yarn link 到全局（供 CI 或其他项目引用 Strapi 源码包），它遍历的是 packages/**/* 并逐个执行 yarn link，与“把外部设计系统链接进 monorepo”方向相反，不要混淆两者。

2. 构建编排由 nx 承担。根 package.json 的 build 脚本为 nx run-many --targets build:code,build:types --nx-ignore-cycles，即按依赖图批量构建所有子包。设计系统作为外部依赖不参与这个图，但你在 monorepo 内改动 Admin 前端代码后，仍应通过 nx 的 watch/构建链路或 examples/getstarted 的 strapi build 来验证端到端效果。

3. 版本一致性有校验。仓库提供了 version:check 脚本（node scripts/check-package-versions.mjs && syncpack lint）检查各包版本一致性。lerna.json 显示仓库版本为 5.7.0（nx 版本，npmClient 为 yarn）。本地链接设计系统只影响运行时/构建时解析，不改变 package.json 声明的版本号，因此不会触发版本校验问题。

本地联调的典型场景与注意事项

• 适用前提：你同时持有 Strapi monorepo 与 strapi-design-system 两个仓库的本地副本，且 Node/yarn 环境与两者要求一致；文档面向的是 Strapi 贡献者/前端开发者，而非最终用户。
• 组件与主题都要验证：如果改动涉及 StrapiTheme 的结构（新增/移除 token），注意 packages/core/admin/admin/custom.d.ts 中 DefaultTheme extends StrapiTheme 的类型扩散，以及 Admin 代码中大量 useTheme 消费点，避免运行时取值 undefined。
• 回退要及时：yarn link -r 的改动会落在 node_modules 中（不属于源码提交），联调结束后务必执行 yarn unlink ../<relative-path-to-strapi-design-system> 还原，否则后续 CI 之外的本地构建会一直使用本地设计系统，造成“只有我机器上能构建”的隐性环境问题。
• 文档入口：该指南在 Strapi 文档站的贡献者导览中也有索引，见 docs/docs/index.md 中 “Working with the Design System” 的引用。

小结

Strapi 的设计系统与主仓库解耦发布，官方提供的联调方案就是 yarn build（设计系统侧）+ yarn link -r（Strapi monorepo 侧）+ examples/getstarted 构建验证 + yarn unlink 回退的四步闭环。整个 monorepo 中 admin、content-manager、content-type-builder 及多个插件的 Admin 端 UI 均消费 @strapi/design-system，配合 StrapiTheme 类型注入 styled-components 主题系统，因此理解这条链接链路是参与 Strapi 前端/设计系统联合开发的前提。