# Nuxt 4+ 的功能切片设计官方 FSD 文档： LLM 参考： ## 核心原则 FSD 使用严格的依赖规则将代码组织到**层**：**每个层只能从其下方的层导入，而不能从上方或侧面导入**。这可以防止混乱的依赖关系——一个小部件永远不会知道使用它的页面，一个功能永远不会触及另一个功能，并且一个实体永远不会依赖于显示它的 UI。 **FSD 专门存在于 `src/` 中。** Nuxt `app/` 目录是运行时 shell - 它使用 `src/` 中的 FSD 代码，但本身并不由 FSD 组织。像 `app/composables/`、`app/middleware/`、`app/plugins/` 和 `app/layouts/` 之类的东西遵循 Nuxt 约定，而不是 FSD 层。 ## FSD 层（全部在 `src/` 中）层按从上（最具体）到下（最稳定）的顺序排列。每个层**只能从其下面的层导入**。页面 ← src/pages/ 中的 FSD 页面切片 — 组成小部件、功能、实体小部件 ← 具有耦合逻辑 + 表示的独立 UI 块功能 ← 可重用的用户交互——逻辑是独立的，UI是可替换的实体 ← 业务领域模型：类型、模式、基本查询、格式化程序共享 ← 框架实用程序、UI 工具包、API 客户端、助手 — 零业务逻辑 ### 图层快速参考层 |包含 |不包含 ---|---|--- **共享** | UI 套件组件、`cn()`、日期/字符串助手、API 客户端设置、类型实用程序 |业务逻辑、领域概念 **实体** | `User`、`Product`、`Order` 类型、Zod 模式、基本 `useFetch` 包装器、模型格式化程序 |用户操作、交互功能 **功能** |身份验证流程、搜索逻辑、购物车操作、表单提交可组合项 |实体定义、布局问题 **小部件** | `ProductCard`、`AppHeader`、`Sidebar`，用自己的数据完成组成的部分 |原始实体数据访问、路由逻辑 **页** |页面切片组装小部件/功能、特定于页面的数据获取 |可重复使用的部件（经过验证后提取） ** ** ## Nuxt 4+ 目录映射项目根/ ├── app/ ← Nuxt 4 应用程序目录（运行时 shell，不是 FSD） │ ├── app.vue ← 根组件 │ ├── pages/ ← 瘦路由 shell（参见“瘦页面模式”） │ │ ├──index.vue │ │ └── 产品/ │ │ ├──index.vue │ │ └── [id].vue │ ├── 布局/ ← Nuxt 布局 │ │ └── 默认.vue │ ├── 插件/ ← Nuxt 插件 │ ├── 中间件/ ← Nuxt 路由中间件 │ └── 可组合项/ ← Nuxt 全局可组合项 ├── src/ ← FSD root — 所有切片层都在这里 │ ├──pages/ ← FSD页面切片（完整实现） │ │ ├── 产品详情/ │ │ │ ├── ui/ │ │ │ │ └── ProductDetailPage.vue │ │ │ ├── 型号/ │ │ │ │ └──useProductDetail.ts │ │ │ └──index.ts │ │ └── (结帐)/ ← 路线组(括号) │ │ ├── _layout/ ← 子路线共享布局 │ │ │ └── CheckoutLayout.vue │ │ ├── 购物车/ │ │ │ ├── ui/ │ │ │ └──index.ts │ │ └── 付款/ │ │ ├── ui/ │ │ └── 索引.ts │ ├── widgets/ ← FSD widgets 层 │ │ └── 产品卡/ │ │ ├── ui/ │ │ │ └── ProductCard.vue │ │ ├── 型号/ │ │ │ └── useProductCard.ts │ │ └── 索引.ts │ ├── features/ ← FSD 特征层 │ │ └── 加入购物车/ │ │ ├── ui/ │ │ │ └── AddToCartButton.vue │ │ ├── 型号/ │ │ │ └── useAddToCart.ts │ │ ├── API/ │ │ │ └── 突变.ts │ │ └── 索引.ts │ ├── 实体/ ← FSD 实体层 │ │ └── 产品/ │ │ ├── ui/ │ │ │ └── ProductPreview.vue │ │ ├── 型号/ │ │ │ ├── 类型.ts │ │ │ └── schema.ts │ │ ├── API/ │ │ │ └── 查询.ts │ │ └── 索引.ts │ └── 共享/ ← FSD 共享层 │ ├── 用户界面/ │ │ ├── UiButton.vue │ │ └── UiModal.vue │ ├── 库/ │ │ ├── 格式日期.ts │ │ └── cn.ts │ ├── API/ │ │ └── 客户端.ts │ └── 配置/ │ └── 常量.ts ├── server/ ← Nuxt 服务器路由（FSD 客户端层之外） ├── public/ ← 静态资产 └── nuxt.config.ts ### 按键映射规则 1. **`src/`** 是 **FSD 根目录**。所有 FSD 层（“pages/”、“widgets/”、“features/”、“entities/”、“shared/”）都位于此处。 2. **`app/`** 是 **Nuxt 运行时 shell**。它遵循 Nuxt 约定，而不是 FSD。它通过导入使用来自 `src/` 的 FSD 代码。 3. **`app/pages/`** 仅包含 **瘦路由 shell** - 它们委托给 `src/pages/` 页面切片。请参阅下面的“精简页面模式”。 4. **`server/`** 完全位于 FSD 之外。服务器路由遵循 Nuxt 服务器约定。 ** ** ## 薄页模式 `app/pages/*.vue` 文件是 **路由 shell**（5-25 行）。它们仅用于 Nuxt 基于文件的路由，并将所有实际实现委托给“src/pages/”中的 FSD 页面切片。薄页： * 从 `src/pages/` 导入页面组件 * 为 i18n 路径映射定义 `definePageMeta({ i18n: { ... } })` (如果使用 `@nuxtjs/i18n` 和 `customRoutes: 'meta'`) * 定义用于验证、布局、路由键的“definePageMeta()” * 渲染导入的页面组件 ### 薄页示例 <脚本设置lang =“ts”> 从 '~~/src/pages/product-detail' 导入 { ProductDetailPage } 定义页面元数据({ 布局：'默认'，验证： async (route) => /^\d+$/.test(route.params.id as string), 国际化：{ 路径：{ cs: '/produkty/[id]', zh: '/产品/[id]', }, }, }) <模板> <产品详情页/> 实际的实现位于 FSD 页面切片中： src/页面/产品详细信息/ 用户界面/ ProductDetailPage.vue ← 全页面实现型号/ useProductDetail.ts index.ts ← 导出 ProductDetailPage ** ** ## `src/pages/` 中的 FSD 页面切片 `src/pages/` 包含完整的 FSD 页面切片 — **不是** Nuxt 基于文件的路由。这些是带有“ui/”、“model/”、“api/”和“index.ts”的常规 FSD 切片。 ### 惯例 * **切片命名**：与域概念匹配的短横线大小写：`product-detail/`、`blog-article-detail/`、`user-profile/` * **路由组** : 括号组相关子路由：`(checkout)/cart/`, `(checkout)/ payment/` * **共享布局** ：路由组内的 `_layout/` 保存跨子路由共享的布局组件 ### 页面切片结构 src/页面/产品详细信息/ 用户界面/ ProductDetailPage.vue ← 主页面组件产品库.vue 产品规格.vue 型号/ useProductDetail.ts ← 页面特定的可组合项接口/ querys.ts ← 特定于页面的数据获取 index.ts ← 公共 API：导出 ProductDetailPage // src/pages/product-detail/index.ts 从 './ui/ProductDetailPage.vue' 导出 { 默认为 ProductDetailPage } ** ** ## 导入和别名 ### 主要模式：`~~/src/` 前缀使用 Nuxt 的 `~~/` 别名（解析为项目根目录）从 FSD 层导入： // 正确 — 主要导入模式从 '~~/src/features/auth' 导入 { useAuth } 从 '~~/src/entities/user' 导入 { type User } 从 '~~/src/shared/ui' 导入 { UiButton } 从 '~~/src/pages/product-detail' 导入 { ProductDetailPage } ### 替代方案：自定义路径别名您可以选择在 `nuxt.config.ts` 中配置较短的别名： // nuxt.config.ts 导出默认的defineNuxtConfig({ 别名：{ '@shared': fileURLToPath(new URL('./src/shared', import.meta.url)), '@entities': fileURLToPath(new URL('./src/entities', import.meta.url)), '@features': fileURLToPath(new URL('./src/features', import.meta.url)), '@widgets': fileURLToPath(new URL('./src/widgets', import.meta.url)), }, }) 然后使用：`import { UiButton } from '@shared/ui'`。两种模式都是有效的 - `~~/src/` 不需要配置，别名更短。 **重要**：不要依赖 Nuxt 自动导入来实现跨层依赖。始终通过切片的公共 API (`index.ts`) 使用显式导入。这使依赖关系保持可见和可执行。 // 正确 — 通过公共 API 显式导入从 '~~/src/features/auth' 导入 { useAuth } // 错误——绕过公共 API 的深度导入从 '~~/src/features/auth/model/useAuth' 导入 { useAuth } Nuxt 自动导入**仅**可接受： * Vue/Nuxt 内置函数（`ref`、`compulated`、`useFetch`、`useRoute`、`navigateTo` 等） * `app/composables/` 中的全局应用程序层可组合项 ** ** ## TypeScript 配置由于 `src/` 位于 Nuxt `app/` 目录之外，因此您必须将其显式包含在 TypeScript 配置中： // nuxt.config.ts 导出默认的defineNuxtConfig({ 打字稿：{ ts配置：{ 包括：['../src/**/*'], }, 共享TsConfig：{ 包括：['../src/**/*'], }, 节点Ts配置：{ 包括：['../src/**/*'], }, }, }) 这确保了所有三个 Nuxt 生成的 tsconfig（客户端、共享、服务器）都包含“src/”中 FSD 代码的类型检查和自动完成。 ** ** ## 切片和段 **切片**是层内的子文件夹，以业务域概念命名： * `src/features/auth`、`src/entities/user`、`src/widgets/product-card` **段** 按切片内的技术角色对代码进行分组： src/功能/auth/ ui/ ← Vue 组件 model/ ← 可组合项、存储 (Pinia)、状态、类型 api/ ← 数据获取（useFetch、$fetch、查询包装器） lib/ ← 特定于该切片的帮助程序 config/ ← 常量、功能标志 index.ts ← 公共 API（必需） ### 命名约定 * **kebab-case** 无处不在：`用户配置文件`、`添加到购物车`、`产品卡` * 域名，而非技术名称：“auth”不是“use-auth-hook”，“product”不是“product-helpers” * Vue 组件：**PascalCase** 文件名匹配组件名称：`LoginForm.vue`、`ProductCard.vue` * 可组合项：**camelCase** 带有 `use` 前缀：`useAuth.ts`、`useProductSearch.ts` ** ** ## 公共API 每个切片**必须**公开一个“index.ts”。外部代码仅从“index.ts”导入。 // src/features/auth/index.ts 从 './ui/LoginForm.vue' 导出 { 默认为 LoginForm } 从 './model/useAuth' 导出 { useAuth } 从 './model/useAuth' 导出 { useProvideAuth } 从 './model/types' 导出类型 { AuthUser, AuthCredentials } **切片之间禁止深度导入：** // 错误从 '~~/src/features/auth/model/useAuth' 导入 { useAuth } // 正确从 '~~/src/features/auth' 导入 { useAuth } 切片内相对导入没问题： // src/features/auth/ui/LoginForm.vue 内部从 '../model/useAuth' 导入 { useAuth } ** ** ## 页面优先工作流程开始 `src/pages/` 中的所有内容。仅在**证明**可重复使用时才提取。需要新功能 │ v 在 src/pages// 内部构建 │ v 用在第二位吗？否 --> 保留在 src/pages/ 中是的 │ v 复制一份（2份即可） │ v 用在第三位吗？否 --> 保持重复是的 │ v 提取。问：“这个逻辑总是与这个特定的 UI 相关吗？” 是 --> Widget（逻辑 + UI 耦合）否 --> 功能（逻辑可重用，UI 可替换）或实体（纯域数据，无用户操作） **规则**：当你有证据（3+用法）时提取，而不是预测。过早的提取会产生不必要的抽象。 ** ** ## 小部件与功能的决定关键问题：**“可以在没有这个特定 UI 的情况下使用该逻辑吗？”** ### Widget——逻辑和UI密不可分 * 始终呈现为一个单元 * 包含自己的数据获取和状态 * 跨 2 个以上页面重复使用，但始终作为一个整体块 src/小部件/工作列表/ 用户界面/ JobList.vue ← 获取数据、渲染列表、处理分页 JobListItem.vue ← 展示子组件型号/ useJobList.ts ← 封装的可组合项，不单独导出 index.ts ← 仅导出 ### 功能 — 逻辑是独立的 * 可组合适用于任何 UI * 提供默认 UI，但可替换 * 逻辑可以无头使用 src/功能/搜索/ 型号/ useSearch.ts ← 独立工作，任何 UI 都可以使用它用户界面/ SearchBar.vue ← 默认 UI，通过 props/inject 接收状态 index.ts ← 导出 useSearch 和 SearchBar ### 快速决策表模块|小部件还是功能？ |为什么 ---|---|--- 搜索去抖结果 |特色| `useSearch` 为不同的 UI 提供支持无限滚动产品列表|小部件 |获取+渲染始终一起进行验证登录表单 |特色| `useAuth` 可在模态、页面、抽屉中重用导航侧边栏 |小部件 |导航项+布局始终耦合喜欢/书签按钮 |特色| `useLike` 独立工作仪表板统计面板 |小部件 |图表+数据始终在一起 ** ** ## 状态管理布局所有状态都位于相关切片的“model/”段中：图案|何时使用 |安置 ---|---|--- 简单可组合 (`useState`) |功能/实体内的共享状态，SSR 安全 | `src/features/auth/model/useAuth.ts` 提供者/注入（`createInjectionState`）|状态范围为组件子树 | `src/features/cart/model/useCart.ts` 皮尼亚商店|全局状态、开发工具、持久性、复杂操作 | `src/entities/user/model/store.ts` ### 提供者/注入模式使用“@vueuse/core”中的“createInjectionState”来获取作用域状态。始终导出一个抛出变体，以便消费者在缺少提供者时得到明显的错误： // src/features/auth/model/useAuth.ts 从 '@vueuse/core' 导入 { createInjectionState } const [useProvideAuth, useAuthRaw] = createInjectionState(() => { const 用户 = ref<用户 |空>(空) 返回{用户} }) 导出 { useProvideAuth } 导出函数 useAuth() { 常量状态 = useAuthRaw() if (!state) throw new Error('useAuth 必须在 AuthProvider 中使用') 返回状态 } ## 数据获取放置什么 |哪里 |示例路径 ---|---|--- 基本查询（读）|实体 `api/` 段 | `src/entities/product/api/queries.ts` 突变（写）|功能 `api/` 段 | `src/features/add-to-cart/api/mutations.ts` 特定于页面的抓取 |页面切片 `api/` 或内联 | `src/pages/product-detail/api/queries.ts` ** ** ## 导入规则（严格） ### 层导入 — 仅向下（在 `src/` 内）页面可以从 → 小部件、功能、实体、共享导入小部件可以从 → 功能、实体、共享导入功能可以从→实体导入，共享实体可以从→共享导入共享可以从 → 导入（什么都没有——只有外部包） `app/` (Nuxt shell) 可以从 `src/` 中的任何 FSD 层导入。 ### 同层隔离同一层内的切片**不能**相互导入： // 错误 — 从 features/profile 导入 features/auth 从 '~~/src/features/profile' 导入 { useProfile } // 正确 - 将共享概念提取到实体或共享从 '~~/src/entities/user' 导入 { type User } ### 跨实体引用（@x 表示法）当实体具有合法的业务关系时，请使用显式的“@x”交叉引用： // src/entities/order/ui/OrderCard.vue 从 '~~/src/entities/user/@x/order' 导入 { UserAvatar } `@x/` 文件夹是受控的交叉导入 API。谨慎使用。 ** ** ## 跨切片通信模式当同一层上的切片需要协调时： 1. **提取到较低层** - 如果两个功能共享一个概念，请将其移至“实体”或“共享” 2. **基于事件的通信** — 使用共享事件总线（`mitt`）或 Pinia 存储来实现松散耦合 3. **更高层的组合**——让一个页面或widget将多个功能组合在一起 ** ** ## Nuxt `app/` 目录（不是 FSD） `app/` 中的所有内容都遵循 **Nuxt 约定**，而不是 FSD。这些文件使用“src/”中的 FSD 代码，但它们本身并未组织到 FSD 层中： Nuxt目录|角色 |与 FSD 的关系 ---|---|--- `应用程序/页面/` |薄路由外壳 |从 `src/pages/` 导入页面组件 `应用程序/布局/` | Nuxt 布局 |可以从 `src/widgets/` 导入小部件 `应用程序/中间件/` |路由中间件|可以从 `src/features/` 或 `src/entities/` 导入可组合项 `应用程序/插件/` |全局设置|可以从任何 `src/` 层导入 `应用程序/可组合项/` |全局可组合项 |只有真正的应用程序范围的问题，而不是 FSD 切片代码 `服务器/` |服务器路由 |完全在 FSD 之外，遵循 Nuxt 服务器约定 ** ** ## 共享层结构 “共享”层**没有切片** - 只有段： src/共享/ ui/ ← 通用 UI 组件：按钮、模式、输入、卡片 lib/ ← 实用函数：formatDate、cn()、debounce api/ ← API 客户端设置、拦截器、基本获取包装器 config/ ← 应用程序范围的常量、环境帮助器、路由名称 types/ ← 共享 TypeScript 实用程序类型每个段都可以有自己的“index.ts”，以实现更清晰的导入。 ** ** ## 搭建一个新切片 src/功能/书签/ 用户界面/ 书签按钮.vue 型号/ useBookmark.ts 类型.ts 接口/ 突变.ts index.ts ← 公共 API（必需）仅创建您实际需要的段。仅具有类型的实体仅需要“model/”和“index.ts”。 ** ** ## 常见错误 ### 1\.将 FSD 层放入 `app/` 中 **错误**：`app/features/`、`app/entities/`、`app/widgets/`、`app/shared/`。 **右**：FSD 层位于 `src/` 中。只有“app/pages/”（薄壳）、“app/layouts/”、“app/plugins/”、“app/middleware/”、“app/composables/”进入“app/”。 ### 2\.胖页面路由 **错误**：将完整页面实现放在 `app/pages/products/[id].vue` 中（200 多行）。 **右**：`app/pages/` 文件是从 `src/pages/` 导入的瘦路由 shell（5-25 行）。 ### 3\.过早拔牙 **错误**：创建 `src/features/fancy-button` 因为“它可能会被重用”。 **对**：保留在 `src/pages/` 中，直到 3 次实际使用证明需要为止。 ### 4\.层数错误 **错误**：将 `useProductSearch` （独立逻辑）放入小部件中。 **对**：问“如果没有这个特定的 UI，这个逻辑可以工作吗？” — 是的意思是功能。 ### 5\.缺少公共 API **错误**：`import { x } from '~~/src/features/auth/model/internal'` **正确**：所有导出都通过`index.ts`。 ### 6\.向上进口 **错误**：从 `src/features/auth` 导入 `src/entities/user`。 **右**：依赖关系仅向下流动 - 实体从不引用功能。 ### 7\.同层交叉导入 **错误**：从 `src/features/auth` 导入 `src/features/profile`。 **右**：将共享概念提取到“entities/”或使用事件。 ### 8\.共享中的业务逻辑 **错误**：`src/shared/lib/useAuth.ts`、`src/shared/lib/useProductSearch.ts`。 **右**：共享仅适用于通用实用程序 - 零业务逻辑。 ### 9\.依赖 Nuxt 自动导入 FSD 层 **错误**：期望 `useAuth()` 从 `src/features/auth/model/` 自动解析。 **右**：通过 `~~/src/features/auth` 公共 API 使用显式导入。 ### 10\.在 `src/` 之外应用 FSD **错误**：将 `app/composables/`、`app/middleware/` 或 `server/` 组织到 FSD 层中。 **右**：FSD 只存在于 `src/` 中。其他所有内容（`app/`、`server/`）都遵循 Nuxt 约定。 ** ** ## 新代码清单在编写或审查代码之前，请验证： * 这属于哪一层？（使用决策树） * 该切片是否有“index.ts”公共 API？ * 所有跨切片导入都通过“index.ts”吗？ * 我是否只从下面的层导入？ * 导入是否使用 `~~/src/` 前缀（或配置的别名）？ * `app/pages/*.vue` 是一个瘦路由 shell（<25 行）吗？ * 小部件还是功能？（问：“如果没有这个 UI，逻辑还能存在吗？”） * 提取是否已被证实（3 次以上使用）或为时过早？ * 所有 FSD 结构的代码都在 `src/` 中，而不是在 `app/` 或 `server/` 中吗？ * `app/` 是否仅包含 Nuxt 运行时问题（瘦页面、布局、插件、中间件）？ ** ** ## 迁移策略对于采用带有 `src/` 根的 FSD 的现有 Nuxt 项目：代码|方法 ---|--- 新模块 |始终遵循 `src/` 中的 FSD 现有的“应用程序/组件/” |迁移到 `src/shared/ui/` 或适当的切片 `ui/` 段现有的 `app/composables/` |分类到 `src/` 中的功能/实体 `model/` 中，或者如果真正是全局的，则保留在 `app/composables/` 中现有的 `app/utils/` |移动到 `src/shared/lib/` 现有 `app/stores/` |移至“src/”中的实体/功能“model/”段现有的胖页面|在 `app/pages/` 中分割成薄壳 \+ `src/pages/` 中的页面切片步骤： 1.创建`src/`目录，包含FSD层子目录 2. 将 `typescript` include (`tsConfig`, `sharedTsConfig`, `nodeTsConfig`) 添加到 `nuxt.config.ts` 3.在`src/`下的FSD结构中启动所有新代码 4. 触摸时逐片迁移现有代码 5. 将胖页面转换为瘦路由 shell + `src/pages/` 切片 6. 更新导入以使用 `~~/src/` 和公共 API 7. 删除空的旧目录

努克斯特FSD

包含技能