# @eldrajs/theme-nuxt 中文文档

规范地址：https://npmcn.com/package/%40eldrajs/theme-nuxt/

版本：0\.4\.2
npm 元数据更新时间：2026-11-10T21:38:03.864Z
中文译文更新时间：2026-11-14T15:22:43.470Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40eldrajs/theme-nuxt
原文对照：https://npmcn.com/package/%40eldrajs/theme-nuxt/?lang=original
项目主页：https://github.com/eldra-is/headless-kit/tree/main/packages/theme-nuxt#readme
源码仓库：https://github.com/eldra-is/headless-kit

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：260 kB，81 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：6 个
- 首次发布：2026-10-17T13:05:04.700Z
- 最新版本发布：2026-11-10T21:38:03.522Z
- 近 30 天下载量：2007（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

Eldra主题的 Nuxt 模块: 有线@eldrajs/vite-plugin-them,网关客户端,草稿上线和工作室预览桥通入一个 Nuxt 4 站点.

## 安装

```sh
npm install @eldrajs/theme-nuxt
```

也可以使用：`pnpm add @eldrajs/theme-nuxt`、`yarn add @eldrajs/theme-nuxt`、`bun add @eldrajs/theme-nuxt`

## README

# @eldrajs/主题-nuxt

Eldra 主题的 Nuxt 模块: 有线 `@eldrajs/vite-plugin-theme`,网关客户端,草稿 覆盖和工作室预览桥进入了Nuxt 4网站. 它将每个公布的页面和 来自 CMS 的动态路由, 写入生成的 `.eldra/manifest.json` 和《加拿大战略计划》 `frame-ancestors` 工作室预览桥需要的头条,并曝光 `useEldraPage` 用于解决 当前路线的页面/模板/输入.

```bash
pnpm add @eldrajs/theme-nuxt
```

## 使用量

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@eldrajs/theme-nuxt'],
  eldra: {
    gatewayUrl: process.env.ELDRA_GATEWAY_URL,
    orgId: process.env.ELDRA_ORG_ID,
    studioOrigins: ['https://acme.eldracms.com'],
  },
});
```

环境: `ELDRA_GATEWAY_URL` 财务报告和审定财务报表 `ELDRA_ORG_ID` 真正的建筑需要。 点 `ELDRA_GATEWAY_URL` 地点 **边缘 API 主机**: 边缘识别出构建符 (单位:千美元)`X-Eldra-Build-Token`所以大楼和访客浏览器都读了 穿过同一个主机.

在提前提交页面列表时, 路由模板列表和类别列表在每次构建中读取一次 (和地产),不是每条路线一次(`@eldrajs/theme-nuxt/prerender`; 请求时间渲染从未 共享读取。 一个过程就是一个构建:共享读取的活度为一个长度 `nuxi generate` 并被清除 当一个先投降开始。 构建日志与计数一行 (单位:千美元)`[eldra] prerender shared reads: N made, M avoided`) (中文(简体) ).

```vue
<script setup lang="ts">
import { EldraLayout } from '@eldrajs/theme-vue';
const { page, layout, blocks } = useEldraPage();
</script>
<template>
  <main>
    <EldraLayout v-if="page && layout" :layout="layout" :blocks="blocks" />
  </main>
</template>
```

## `eldraRouteKey` - 需要你帮忙 `<NuxtPage>`

给你 `app.vue` 路径键 此模块自动导入 :

```vue
<!-- app/app.vue -->
<template>
  <NuxtPage :page-key="eldraRouteKey" />
</template>
```

这可不是化妆品 **生成** 网站. `nuxi generate` 将每个路由写入为 `<route>/index.html`,而静态主机对文件住址的URL有分歧——有些服务 `/products/ash-glaze-mug`,其他人用重定向回答 `/products/ash-glaze-mug/`当 访问者登陆的 URL 不同于页面预发路径 Nuxt 重新导航 页面水合物时介于二者之间;一个覆盖所有页面的默认路由键插入 splate 参数,所以这两个拼音键不同,而Vue会破坏并再创建页面—— 和每个街区在它上。 每个街区 `setup` 然后运行两次, 所以每个阅读 商业块制作 出去两次 两例中只有一次上架过 所以DOM里没有什么东西能把它送走.

`eldraRouteKey(route)` 由 cononical 路径按键——相同身份 `useEldraPage()` 决定 内容在下面——所以这个动作是无操作的. 在此添加前的主题脚手架应添加 装订.

## 生成站点上的路由解析度

在一个 **在浏览器中静态构建**, (中文(简体) ), `useEldraPage()` 确定从建筑而不是从 网关. `nuxi generate` 船载它预设的路径列表(Nuxt的应用显示, `/_nuxt/builds/meta/<buildId>.json`),该列表回答两个问题 解析器用来问 网关 :

-   **道入于楼.** 其页面、模板和条目载于 `_payload.json` 纳克特自己的 有效载荷插件装入 `router.beforeResolve`,在页面组件存在之前——所以是一个客户端 导航在两条预交路由之间,使目的地在同一勾选中 `pending` 从不真实 也没有读过任何网关.
-   **道不在楼.** 它不存在: `useEldraPage()` 返回空路由 (单位:千美元)`page === null && template === null`)直走,所以主题画出它尚未找到的外壳 5人不读它过去用来得出同样的结论。 这条路线自 建筑也不在文物中——出版会引发重建,这就是建造的原因 权力.

3种情况保持了旧的动态解析,是查阅清单的原因 而不是假设:

-   **工作室预览.** 在允许范围内 `studioOrigins` 框架 路由可以是草稿,也可以是 未出版的页面或一个没有构建过的路径,所以每个决议都是活的——从 首先,在桥还没打招呼之前.
-   **`nuxi dev`。 。 。 .** 德夫服务器载着一个没有预兆的货单.
-   **安全部门改革部署** (单位:千美元)`nuxt build` 加上节点服务器,原因相同: 构建,所以一个空的预发列表意味着“此构建预发无任何” , 绝不是“ 此路径确实” 不存在".

### 一项决议 **失败** 不是一个缺失的路径

上面的空路是一个答案:没有这样的一页. 读取的网关无法回答的是 没有,而且 `useEldraPage()` 将两者分开——失败的决议携带 `error` 决议 本身(`ResolvedEldraRoute.error`),这样 `error` 时为非无 `page`编号 :`template` 无效和 a 主题可以绘制其错误分支,而不是未找到的外壳。 错误存在于分辨率上 而不是在混凝土内部 因为 `useAsyncData` 保留 **一个** 按路由键输入并运行 只有第一个呼叫者的处理器:一个调用的主题 `useEldraPage()` 页面上的两次(用于插件) 页面组件旁边的目录路由)否则会在一个呼叫和一个 普通空路径.

**在服务器上, 这样的路径被响应 `500`。 。 。 .** Nitro的预触器标记了一个非200路由失败 在它写东西之前, 所以一个无法被问及的页面 已经不存在了 文物和命名在前置记录中,而不是被写成主题的未找到外壳 在访客可以到达的道路上 说对了 `nitro.prerender.failOnError` 如果一个建筑不能运送 没有每一页——状态本身就把错误的一页变成缺失的一页,而那面旗帜就变成了 将一个丢失为失败的构造 。 注意,真实暴露约为路线数的两倍: `crawlLinks: false` Nitro仍然在给每页发稿 `_payload.json`,解决路径 再来一次.

一个建筑与 **没有 `ELDRA_GATEWAY_URL` 编号 : `ELDRA_ORG_ID`** 两种情况均豁免: 根据定义,这样一条路由就解决了平原空路由,没有 `error` 和主题 制造出它的静态外壳, 这是整个脚手架建筑的点.

这也是为什么 `eldraRouteKey` 需要上文而不是咨询: canonical 路由是让可混凝土解析其页面正在创建的路由。 坚果 将自己的路由通过私人注入 Nuxt 的应用模块, 手持页面 无法到达装入包件中; `useEldraPage()` 因此读取路由器的 承诺路线和 把它钉上页的一生.

## 当网关速率限制构建时

网关将客户端限制在每分钟若干个请求. A 类 `generate` 一个真正的网站是 从一个地址读取了上千份 每一个页面,每一个路由模板,每一个目录文档, 因为每一页都有 `_payload.json` 决定: 路由再次——所以一个大型建筑例行满足这个限制. 网关的答案是 `429`; 与 `failOnError` 设定,其中之一用来结束建筑.

**无需为此配置 .** 每个网关读取——这个模块自己的前置读取, 主题在请求时间读取,平台在后面读取 `commerce`编号 :`locales` - 重审 a 回答的天能请求 `429` 或者说 `503` (和中断的连接),荣誉 `Retry-After` 以数倍的速度退缩 包括第一次 费率限制 等待而不是战斗.

指针是用于一个有超乎寻常的狭长界限的网关,或者用于一个应该会迅速失败的建筑物:

```ts
// nuxt.config.ts
eldra: {
  // The defaults. `attempts` counts the first request; `{ attempts: 0 }` turns retrying off.
  retry: { attempts: 5, baseDelayMs: 250, maxDelayMs: 5000 },
}
```

它在公共运行时间配置中携带, 所以一个商店前端 建设自己的 `@eldrajs/sdk` 商务客户端读取可发送同样的政策(`useRuntimeConfig().public.eldra.retry`(b) —— 开始者会的.

两个氮键坐在它旁边 这个模块也不是用来设置的: `nitro.prerender.concurrency` (单位:千美元)**1个** 默认情况下,这已经是最温和的设置——除非您有 并把它提起来 `nitro.prerender.retry`编号 :`retryDelay` (默认为3×500 ms),它重新给出一个路径 其反应是techt的可重复状态之一——408,409,425,429,500,502,503,504,以及 因此,500本模块以失败的解析度回答,但不是404.

**新的失败模式是一种会爬行的构造,而不是失败的构造.** A 类 `Retry-After` 很荣幸 到一分钟,和 `maxDelayMs` 封顶 _计算_ 而不是等待 门要求的, 所以4个在限时等待 持续要求一分钟大约4分钟 **一个** 改为: 时 Nitro 自己的重击,在 `concurrency: 1`,同时没有输出,也没有出错。 这是 意图(一个等待的建筑胜过一个失败的建筑),但这是没有人能做的 外出诊断,所以 `retry: { attempts: 0 }` 是一个故障快速杠杆:一个请求,一个 `429` 显示它以前的样子.

**同样的政策是读取一个跳跃触发器**,不仅仅是构建:运行时插件的客户端 服务SSR,客户端路由更改和工作室预览. 符合费率限制的访客 因此,客户端导航等待——最多一分钟 `Retry-After` - 他们之前在哪里 显示一个错误,对于暂时的限度来说,这是两个错误中更好的。 一个更愿意 在浏览器中失败的速度快于等待设置较小的 `attempts`;前置读取使用相同的 价值,所以是一个取舍,而不是两个.

## 编目后路由模板

一个路由模板 `schemaApiId` 实值 `catalog:product`, (中文(简体) ), `catalog:collection` 或者说 `catalog:category` 由商店的目录而不是 CMS 计划支持: 模块预发 每个活性产品,收集或类别,一个途径,以及 `useEldraPage()` 解析对象从 路径.

```vue
<script setup lang="ts">
const { template, entry, catalog, layout, blocks } = useEldraPage();
// catalog is { kind: 'product' | 'collection' | 'category', slug, path? } here, and null on every
// other route. `path` is set for a category and for nothing else.
// entry.data carries the binding paths a catalog template addresses —
// product: slug, title, description, status, categoryId, tags, variants[], images[]
// collection: slug, title, description, productCount, image
// category: slug, title, path, ancestors[], children[] (+ description as plain text, and
//           productCount, when the catalog read carries them)
</script>
```

分类目录的 sult 无法解析空路, 因此主题无法找到 壳. 在一代人的时间里,无法成为一条路线的一发子弹被用警告来命名它 建筑继续.

### 分类是筑巢的,只有犬科

类别路由的图案结束于 a **包罗万象** 参数 - `/categories/:path*` ——及其 `slugField` 实值 `path`。参数匹配一个或多个段并随附 `/`数字 : 一个类的犬行道是它的先祖的鼻涕,先是根,然后是自己的 (单位:千美元)`/categories/billinn/bilstolar`) (中文(简体) ).

没有读取路径,所以整个类别列表每个请求读取一次 路径的片段被弹出从树上走下. **只有条条路能解决** - 叶子上 其自己的、错误的父体和后继的额外部分是每个未找到的外壳而不是一个 重新定向—— 和前手传 产生准确的这些 犬道,一个类别,时间 网站的地方。 列表无法放置的类别( 没有 swit, 或列表的父文件没有) 根本没有一条路,也没有树下的树.

A 类 `link` 字段指向一个类别,通过同一路径解决: `collectLinkTargets` 读取 基于这个原因,它不能设置的目标 使文字变得简单而非链接 以未找到的外壳回答.

`studioOrigins` 必须明确——这个模块从不提供广泛的后退源源源 预览桥. 见 [实例/启动- nuxt](https://npmcn.com/package/examples/starter-nuxt) 主题和主题 [文件/主题](https://npmcn.com/package/docs/themes.md) 为融合指南.

## 店里卖的东西

该模块在建设过程中读取了该组织的商务设置,并将其放在 运行时间配置在网关 URL 和 org ID 相邻 . `StoreCommerce` 完全为此导出, 因此,按键的形状不会按主题重新声明:

```ts
import type { StoreCommerce } from '@eldrajs/theme-nuxt/commerce';

const raw = (useRuntimeConfig().public.eldra as { commerce: StoreCommerce | null | '' }).commerce;
const commerce: StoreCommerce | null = typeof raw === 'object' ? raw : null;
```

`commerce` 实值 `null` 当商店没有配置商务时, 当站点没有配置时 网关证书,或读取失败时——构建打印出一个警告( 命名原因时) 因为没有人能拿到的货币 应该需要一个符号,而不是部署. 将价格格式化的主题视为“放弃一个普通数字”,绝不是货币 猜;启动者在 `app/storefront/money.ts`。 。 。 .

阅读密钥时, Nuxt 自身序列化的一个细节很重要: a `null` 公开运行时间配置 值以 **空字符串**所以在一家没有出版的商店 `commerce` 实值 `''` 而不是说 `null` (模块的) `locale` 执行相同)。 处理任何非对象 作为"没有货币"——而不是一个畸形的记录——并且只抱怨一个存在但 不完整 .

该模块没有自行提供超载,目的:平台发布货币 因此主题侧设置只能重新标出真实金额. (Nuxt自己的公共运行时间配置环境压倒了——) `NUXT_PUBLIC_ELDRA_COMMERCE_CURRENCY` 财务报告和审定财务报表 它的兄弟姐妹——只要Nuxt在请求时读取运行时配置,就仍然适用,就像它适用于每一个 其他公用钥匙。 在一个先发制人的网站里,它没有什么可以覆盖的: 值被烤成 每页的有效载荷在构建。 ) 它在构建时而不是在浏览器中读取,因为每个价格 预发页面格式化.

## 网站服务的地点

该模块在构建过程中读取了组织配置的内容定位一次,并放入 在运行时配置旁边 `commerce`。 。 。 . `StoreLocales` 完全用于此目的导出 :

```ts
import type { StoreLocales } from '@eldrajs/theme-nuxt/locales';

const raw = (useRuntimeConfig().public.eldra as { locales: StoreLocales | null | '' }).locales;
const locales: StoreLocales | null = typeof raw === 'object' ? raw : null;
```

`locales` 实值 `{ default, supported }` 与 `supported` 默认第一,或 `null` - 对于一个 为没有网关证书而建的网站配置无字的组织,并改为 失败(最后一个,只有那个,打印出一个警告 命名原因). `null` 表示 站点行为与当地人存在之前完全相同:一个没有前置站点,没有语言切换器. 与 `commerce` 适用,即 `typeof` 警卫 上面是用来表示的.

一个主题很少需要读取密钥本身:模块将其转换为路由(见下文)和 `useEldraLocale()` 是可复数的回答“哪一个语言是此页面,什么是 还有其他的".

## 本地前置路由

有两个或两个以上本地地址, 网站为默认本地地址服务 `/` 和所有其他支持 路径前缀下的地块 —— `/is-IS/products/ash-glaze-mug`。第一个路径段选择 语言(对大小写不敏感,与所储存的组织拼写相匹配)和 其它路径的解析与它未设置的解析完全相同; 每个网关为该页所读 拿着 `locale`。 。 。 . `/<default-locale>/…` 是故意的,这是故意的 **没有** 生成和解决 未知路径, 因为默认的地块位于 `/` 只有这个.

路径段不翻译:每个前缀下都有一个页面处于默认-本地状态,所以 `/is-IS/about` 是冰岛对同一文件的渲染 `/about` 服务。 交接传球 因此列出每个内容路径一次,并写出每个地块——页面,路由模板, 分类路线和种子 `cart`编号 :`wishlist`编号 :`search` 页面相同.

`eldra.locale` 编号 : `ELDRA_LOCALE` 保持它一直有的意义: **默认** 语言。 命名一个组织支持的地方 移动该地方 `/` 和前缀 ; 命名其他任何(或针对一个没有本地地址的组织部署) URL 并仍然转发每个读取的值 .

模块给出每一页 `<html lang>` (单位:千美元) `rel="alternate" hreflang` 每个被支持的链接 语言( 加) `x-default` ——这个主题对两者都没有任何增加.

```vue
<script setup lang="ts">
// Auto-imported, like `useEldraPage`.
const { active, defaultLocale, supported, name, path, switchPath, select } = useEldraLocale();

// `path()` prefixes one same-site destination for the active locale, and is idempotent.
const cartHref = computed(() => path('/cart'));
// `switchPath()` is the same page in another language, query and fragment included;
// `select()` navigates there.
</script>
```

`name(locale)` 是一个切换器的选项标签。 没错 已解决 **一次,在服务器上**,并在有效载荷中载入: `Intl.DisplayNames` 是伊斯兰法院联盟的数据和a 渲染器和浏览器不需要有同样的东西——节点回答"íslenska (Ísland)"用于 `is-IS` 在其中,一个缩小的ICU浏览器构建“冰岛语(冰岛)”的答案——这样一页就可以让每一方 计算自己的标签会水合到不匹配和再油漆.

链接已经处理好 `useEldraLink()` 决定 a `link` 字段红外线 在活动区域下,一个主题的路由器-链接组件应该将每个内部 `to` 结束 `path()` 一次(启动器) `app/components/EldraRouterLink.vue` 参考文献).

## 发展

`src/runtime/**` 由 Nuxt 在构建/ Dev 时间编译, 而不是由 `tsc` 进口 `nuxt/app` 财务报告和审定财务报表 Nuxt 的虚拟模块(`#imports`, (中文(简体) ), `virtual:eldra/*`),它只存在于 Nuxt 架构中 图表. `tsconfig.json`是因为 `include` 缩小为 `src/index.ts` 财务报告和审定财务报表 `src/module.ts` (单元) 条目,它只导入可解析的软件包——并通过它导入无框架运行时文件 它与可堆肥者分享) `pnpm typecheck` 证明该部分 `tsc` 能够 实际解析; 到达 Nuxt 的运行时文件仍然被键入到 `nuxt-module-build build` 和通过消费 Nuxt 应用程序(参见 `examples/starter-nuxt`是因为 `nuxi typecheck`) (中文(简体) ).

## 常见问题

### @eldrajs/theme-nuxt 是什么？

Eldra主题的 Nuxt 模块: 有线@eldrajs/vite-plugin-them,网关客户端,草稿上线和工作室预览桥通入一个 Nuxt 4 站点\.

### 如何安装 @eldrajs/theme-nuxt？

在项目目录运行 npm install @eldrajs/theme-nuxt，或使用 pnpm add / yarn add / bun add。

### @eldrajs/theme-nuxt 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @eldrajs/theme-nuxt 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @eldrajs/theme-nuxt 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @eldrajs/theme-nuxt 可以商用吗？

@eldrajs/theme-nuxt 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @eldrajs/theme-nuxt 的下载量有多少？

根据 npm 官方下载统计，@eldrajs/theme-nuxt 在 2026/10/14 – 2026/11/12 这 30 天内被下载 2,007 次，日均约 67 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @eldrajs/theme-nuxt 还在维护吗？

最新版本 0\.4\.2 发布于 2026/11/11（3 天前）；至今共发布 12 个版本，其中过去 12 个月发布了 12 个；首次发布于 2026/10/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。