# @elytracms/cli 中文文档 规范地址：https://npmcn.com/package/%40elytracms/cli/ 版本：0\.0\.113 npm 元数据更新时间：2026-11-07T10:55:35.254Z 中文译文更新时间：2026-11-13T15:31:26.500Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40elytracms/cli 原文对照：https://npmcn.com/package/%40elytracms/cli/?lang=original ## 关键信息（来自 npm 元数据） - 包体积（解压后）：253 kB，18 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - Node.js 要求：\>=22\.18\.0 - 运行依赖：1 个 - 首次发布：2026-06-25T18:35:04.640Z - 最新版本发布：2026-11-07T10:55:35.086Z - 近 30 天下载量：4811（2026-10-14 至 2026-11-12，npm 官方下载统计） - 已发布版本数：60（近 12 个月 60 个） ## 中文简介 Elytra CLI——在一个指令下运行一个消耗力的Repo工作室,前端和Convex后端. ## 安装 ```sh npm install @elytracms/cli ``` 也可以使用：`pnpm add @elytracms/cli`、`yarn add @elytracms/cli`、`bun add @elytracms/cli` ## README # @elytracms/cli (英语) 伊利特拉CLI——经营一个 [伊莱特拉](https://www.npmjs.com/package/@elytracms/core) 消耗Repo的工作室, 送货前端, 和康维克斯后端 在一个命令下. 安装在脚手架上的项目中作为独立项目 [`create-elytra`](https://www.npmjs.com/package/create-elytra); 其编号 `dev`编号 :`build` 脚本调用 `elytra`。 。 。 . ## 图标 ``` elytra dev Start the studio + frontend (and Convex in connected mode) together as one supervised process group. One Ctrl-C stops everything; if any process exits, the rest are torn down. elytra build Build the studio + frontend (and deploy Convex in connected mode), in order — failing as a whole if any step fails. Optional target (the per-app Vercel build commands): elytra build studio Convex deploy coupled with the studio build (functions + client in lockstep) elytra build frontend frontend build only elytra init First-run setup: provision Convex, generate the auth signing keys, verify readiness. Idempotent — safe to re-run. elytra doctor Diagnose the active deployment's readiness and print each fix. Includes the expected deployment env vars, reported set/missing by NAME only — values are never read into the report or printed. When the publish revalidate pair is set, also sends a signed no-op ping to the endpoint to prove the publish → live chain end to end. Also checks your cms/ route set for URL conflicts (see below), and reports the generated-previews artifacts (manifest present, image files present, no strays — warnings only; previews are optional). Read-only; exits non-zero if any check fails. elytra previews Render every canvas-eligible component's fixtures against your theme and write committed insert-menu preview artifacts: 640×400 WebP images in studio/public/elytra-previews/ plus an importable studio/elytra-previews.json manifest (per-entry input hashes — re-running with unchanged inputs rewrites nothing; removed components' images are pruned). Wire it with `generatedPreviewsFromManifest` from `@elytracms/studio/customization` (two lines — see the docs). Rendering needs Playwright once (optional, on demand), at the workspace root: pnpm add -Dw playwright && pnpm exec playwright install chromium Options: --check verify the input hashes without rendering (no Playwright needed); exits non-zero when previews are missing/stale/orphaned. Wire into CI/builds. --port harness dev-server port (default: first free 5440+) elytra help Show help elytra version Show version ``` 从Elytra项目内部的任何地方运行(目录 `elytra.config.ts`) (中文(简体) ). 每个子命令接受 `--help`编号 :`-h` 并打印自己的用法——惰性:否 项目检查,没有进程产出,没有网络呼叫,没有写字. `elytra dev --help` 从不启动服务器; `elytra doctor --help` 从不运行网络 诊断; `elytra build --help` 永远不能验证一个目标. ## 项目布局 工作室的应用程序,前端的应用程序和主题在 `studio/`, (中文(简体) ), `frontend/` 财务报告和审定财务报表 `components/theme.css` ——脚手架布局——除非 转接根 `package.json` (外边) `elytra.config.ts`(a) 宣布: ```json { "elytra": { "studio": "./apps/editor", "frontend": "./apps/site", "theme": "./styles/site.css" } } ``` 每把钥匙都是可选的. 无效的段落或未声明的路径 报告存在(`elytra doctor` 失败 `project-layout`; 其他命令 拒绝开始)——绝不沉默地被默认取而代之. 完全规则:指南 06- CLI 参考,安装 `@elytracms/core` (单位:千美元)`node_modules/@elytracms/core/dist/guide/06-cli-reference.md`) (中文(简体) ). ## 模式意识 CLI 读取工作室的 Env 文件 —— Vite 的负载 (单位:千美元)`.env`, (中文(简体) ), `.env.local`, (中文(简体) ), `.env.`, (中文(简体) ), `.env..local`)——通过同平型 后端-模式解析工作室运行,所以两人从未有异议: - **游戏场** (单位:千美元)`VITE_ELYTRA_MODE=playground`)——运行工作室+前端 只有;没有Convex. - **已连接** (单位:千美元)`VITE_CONVEX_URL` ——也运行 `convex dev` (或部署在 一旦部署到位(建造)`CONVEX_DEPLOYMENT` (现). - 任何其他 `VITE_ELYTRA_MODE` 值是工作室的启动错误,以及 CLI 名字也一样. 它主持并拥有过程的生命周期;它不重新执行Vite, 下个,或 Convex —— 每一个步骤都弹出到基础工具上并继承其 手表/高压/建构行为. ## 开发端口 工作室默认为 `:5180`,前端为 `:3000`一个杠杆同时移动 一起设置 `ELYTRA_DEV_PORT_OFFSET` 内 `studio/.env` (例如:. `100` - 工作间 `:5280`,前端 `:3100`与Elytra计划一起运行 没有冲突. `elytra dev` 读它从 `studio/.env` 并转发给 两个孩子的过程; 工作室自己的 `vite.config.ts` 还直接读出来 (这样) `vite dev` 独立运行也荣誉。 取消设置( 默认) 和今天一样. ## 部署(维也纳) 部署是被推后驱动的——没有 `elytra deploy`。消费回购 部署为 **两个Vercel项目** 同一基特雷波,加上Convex 由工作室构建的部署将功能推向: | Vercel项目 | 根目录 | 构建命令 | | --- | --- | --- | | 工作室 | `studio` | `pnpm exec elytra build studio` | | 前端 | `frontend` | `pnpm exec elytra build frontend` | `elytra build studio` 覆盖 Convex 推荐的 Vercel 集成: 它运行 `convex deploy --cmd 'pnpm run build'`,它推动您的 Convex 函数和 然后运行工作室的构建, 将部署 URL 注入其内嵌 (单位:千美元)`VITE_CONVEX_URL`) (中文(简体) ). 已经建成的演播室总是符合它的职能 已部署,而且没有手设的 URL 来漂移与同步 部署密钥的目标. `elytra build frontend` 运行 Next.js 仅构建到 前端在运行时而非构建时读取其 Convex URL . ### 哪个洞住在哪架飞机上 信封住在三架飞机上 将它们分开——大多数错位是一个价值 设置在错误的平面上 : 1. **当地 `.env` 文件** (单位:千美元)`studio/.env`, (中文(简体) ), `frontend/.env`——地方发展 只有这个 吉提格诺德,他们从未到达韦尔塞尔或康维克斯部署. 2. **Vercel 工程环境** 每个Vercel项目的建设和运行时间: - _工作室项目 :_ `CONVEX_DEPLOY_KEY` (生产部署键生成) 在Convex仪表板中——它选择 **财务报告和审定财务报表** 授权部署). 不要手设 `VITE_CONVEX_URL`; 构件注入(上). 可选 : aI 提供者密钥( E)`ANTHROPIC_API_KEY`,或 Vercel AI 网关) 演播室的AI路线——一个主机/服务器入门,从不 `VITE_`\- 预设. - _前端项目 :_ `ELYTRA_CONVEX_URL`, (中文(简体) ), `ELYTRA_PROJECT_ID`, (中文(简体) ), `REVALIDATE_SECRET`, (中文(简体) ), `DRAFT_PREVIEW_TOKEN` - 看脚手架的 每对都用CONNECT.md. 3. **Convex 部署掩体** ——设置 `npx convex env set` (从) `studio/`(三); 在Convex仪表板上可见但无 文件: 认证签名密钥( e)`JWT_PRIVATE_KEY`, (中文(简体) ), `JWKS` - 通过 `npx @convex-dev/auth`, (中文(简体) ), `SITE_URL`,即时的一对 `CANVAS_REVALIDATE_ENDPOINT` 编号 : `CANVAS_REVALIDATE_SECRET`,以及 `DRAFT_PREVIEW_TOKEN` (秘密和标志必须与他们的 前机对等机). `elytra doctor` 诊断这架飞机 准备. 因为3号机没有档案 很容易被忽略 `elytra doctor` 因此列举了那里的预期值(auth keys, `SITE_URL`, (中文(简体) ), 即时打印的一对, 草稿预览符, 加上 AI 提供者密钥 当AI航线出现时,在工作室-主机上进行报告) **设置或缺少,仅按名称**: 医生解析出姓名 `npx convex env list` 并丢弃现场的每个值——值从不存储, 打印或登录。 缺少所需的 var( 认证密钥) 失败运行 精确的固定线; 缺少建议 var (`SITE_URL`,AI键, 草稿预览符)是一个命名的警告,不会改变退出 代码。 该工作室的启动时间"部署设置"屏幕列出相同的 所以CLI和工作室讲一个故事. 这个 **即时打印对** —— 说 `CANVAS_REVALIDATE_ENDPOINT` 财务报告和审定财务报表 `CANVAS_REVALIDATE_SECRET` ——得到特殊待遇,因为出版路径 **沉默无声** 或未设置 : 写入- 选择点触发器 将重新验证的 webhook 列表, 动作会提供它, 仅同时两种 已经设定。 发布后, 在调用前绝不更新现场网站, 没有 任何地方都出错。 两者均失踪,是一种警告,其后果是: 没有交付前端的项目可以合法地使其不设; **一个 两集失败** 运行,因为一个半成型的对没有 合法阅读(记录在脚手架的CONNECT.md中,设置在 一个外壳块,所以部分状态 更可能是一个中断设置 而不是故意的选择。 当对IS设定时,医生走一步 并证明链末端: 它 POSTs a **已签名的 ping** (单位:千美元) `probe` 事件——一个没有缓存标记的事件)到终点。 A 类 200个 `{"revalidated":[]}` 通过(端点可以到达,前端) `REVALIDATE_SECRET` 匹配, 前端会显示此引擎的事件 a 401作为 Convex 和前端主机之间的秘密不匹配而失效; a 400 以 skew 版本失败( 前端运行不同的 Elytra 版本); 网络错误只警告( 无法从您的机器中获取与 断了 —— Convex 可能仍然到达). 双子的值在进程内读取 仅供平面使用,从未印刷过。 (不再有第三,范围: 前端获取它的缓存标记 其本身 `ELYTRA_PROJECT_ID`. ) (中文(简体) ) 这个 **草稿预览符号** —— 说 `DRAFT_PREVIEW_TOKEN` - 门的部署 `draftSnapshot` 查询,并且必须等于前端主机本身 `DRAFT_PREVIEW_TOKEN` (同样的秘密 打开前端的 可预览的路径; 医生只能看到 Convex 部署的一面; 它 没有 `pairWith` 因为它真正的伙伴 住在飞机上 医生不识字。 缺少它是一个警告: 预览草稿已关闭 在所有地方(两边401个),直到设定——一个从未使用过的项目 草稿预览可以合法地保留它. ## 路线冲突( E)`elytra doctor`(中文(简体) ) 路由是代码,所以一个路由冲突是构建时错误 `elytra doctor` 报告它: 两条路径匹配完全相同的 URL 失败运行 罪证和图案 这件事不需要部署 检查也以操场模式进行. 当工作室的道具安装后,医生执行 `elytra.config.ts` 通过工作室自己的维特 并判断它解决的路线—— 究竟什么 工作室和送货服务。 没有他们,它会回到读你的 项目的 `cms/index.ts` 原产地 `collections` + 键 `routes` 脚手架的 `elytra.config.ts` (通过)和 `route-conflicts` 行说 他们俩被判决。 那棵树很平整,没有反应的TypeScript通过常规, 因此CLI从本土导入——没有捆绑机,没有Vite,没有dev服务器. 两个 倒置的后果值得了解: - 它需要一个在本地运行 TypeScript 的节点(**第22.18条**) (中文(简体) ). 在一个更古老的节点上 检查报告“ 这里没有检查 ” , 并列出版本的名称—— 从不假 通过. - 如果路由集无法读取任何原因( 否) `cms/index.ts`,模块 中, 导入 CLI 无法解析 `tsconfig` 路径 别名, 类型脚本语法 节点不能剥去,或者 `routes` 导出 检查报告 **为什么**,因为"这里没有检查。" 从来没有 撞倒医生 永远不要声称你的路线很好. ### 冲突等级挂载 分级挂载( N)`/:path*`, (中文(简体) ), `/docs/:path*`)不是路由器路线:它是被拉走的 退出路由器,并按请求解决 树。 所以上面的路由冲突检查 根本看不到挂载, 还有第二秒 横行.. `mount-conflicts` 以他们所宣称的来评判他们: - **在同一路径上挂起的两个收藏失败了运行.** 他们声称 相同的 URL 空间,唯一分开它们的东西就是声明命令. - **在他人的 URL 空间内嵌入的挂载是一个警告 .** 这是真的 影子,但只有 外部收藏的树 实际构成路径 进入内山的前缀——即内容,一个CLI看不到,所以 命名优先是诚实的, 并且失败你的建构不会是. 被命名的优先权是值得直言的,因为没有其他办法: **挂载按声明顺序进行试验,而不是按具体情况进行**,第一个 其收藏解决了该 URL 的文档胜出 。 已声明根挂载 因此,首先要超越更深的路线——与普通的路线如何相反 表现,其中更多的静态段总是取胜。 声明更具体的挂载 先说. ### 无益的声明 第三行—— `unreachable-routes` - 问与两者不同的问题 上面:不是"两个宣言争斗吗?"而是"这个宣言能服务于吗 什么都行吗?" 三个形状都绊倒了,过去404个都默默地 在任何地方都没有提出问题: - **在一个挂载的 URL 空间上的全动态路径** a 包括: **警告**。 。 。 . `/:slug` 匹配 _每个_ 单块 URL,所以 `/:path*` 上面有咨询 仅当路径解决了没有文档时。 没什么是无条件的 无法到达(解脱者倒下——看) _优先发言_ 不过 高度由您决定 **内容**: 页面 与后弹道相撞的路径 都无声无息 侧被告诉. `/blog/:slug` 一直很好 静态部分索赔 只有你刻出的名字空间 这是 _全部_\- 动力图案需要 整个深度. - **在收藏品上挂载无法备份** 没有 `parent` 自我关系, 故无巢道可作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作作 都说吧 解析器悄悄地跳过这样一个挂载;它下面的每个 URL 。 这个 一个 **失败** 运行 : 没有内容和命令可以让它发挥作用. - **充满动态前缀的全集** (单位:千美元)`/:lang/:path*`(a) ——还a **失败**。 。 。 . 它在两个方向上都死了 每个路由器都把它当作一个包罗万象的 挂载由它构建,因为挂载前缀必须是静态的. 每个地方 挂载, 声明每个地方有一个挂载 : `{ pattern: '/de/:path*', locale: 'de' }`。 。 。 . ### 优先级: 匹配不是结果 一条路总是胜过一个山 **对于它能够实际服务的 URL**当 a 路由匹配一个 URL , 但没有解决那里的文档 —— 没有带有该 swit, 或 没有从这个角度发表——解决者属于等级 而不是返回404号 这么说 `/blog/:slug` 不采取 `/blog/*` 远离页面树的命名空间:一个页面 at `blog/kid` 服务, 它停止服务的时刻 _员额_ 带弹片 `kid` 已存在. 值得了解的后果:哪些收藏服务于这种URL取决于 不仅在路线上存在,而且从每个角度加以评价——a 仅草稿后在预览中获胜,而已公布的页面仍为现场服务. **在此不检查方向循环 .** 由于EC-303重新定向是编辑性的 后端的数据,而不是代码——一个CLI没有编辑数据. 工作室检查 (和路线冲突,以及路线上的一半) `unreachable-routes`(中文(简体) ) 活在地上,在地上行走,因为它既控制着交通路线,又控制着交通 引出铁路. ## 常见问题 ### @elytracms/cli 是什么？ Elytra CLI——在一个指令下运行一个消耗力的Repo工作室,前端和Convex后端\. ### 如何安装 @elytracms/cli？ 在项目目录运行 npm install @elytracms/cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 elytra，可以用 npx elytra 直接运行。 ### @elytracms/cli 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/elytracms\_\_cli 是否存在。 ### @elytracms/cli 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @elytracms/cli 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=22\.18\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @elytracms/cli 可以商用吗？ @elytracms/cli 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @elytracms/cli 的下载量有多少？ 根据 npm 官方下载统计，@elytracms/cli 在 2026/10/14 – 2026/11/12 这 30 天内被下载 4,811 次，日均约 160 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @elytracms/cli 还在维护吗？ 最新版本 0\.0\.113 发布于 2026/11/07（6 天前）；至今共发布 60 个版本，其中过去 12 个月发布了 60 个；首次发布于 2026/06/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。