# @fluid-app/fluid-cli-theme-dev 中文文档

规范地址：https://npmcn.com/package/%40fluid-app/fluid-cli-theme-dev/

版本：0\.1\.1226
npm 元数据更新时间：2026-11-16T17:53:25.526Z
中文译文更新时间：2026-11-16T17:02:37.016Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40fluid-app/fluid-cli-theme-dev
原文对照：https://npmcn.com/package/%40fluid-app/fluid-cli-theme-dev/?lang=original

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

- 包体积（解压后）：16.6 MB，326 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：12 个
- peer 依赖：playwright \>=1\.40\.0
- 首次发布：2026-03-12T19:48:36.800Z
- 最新版本发布：2026-11-16T17:53:25.273Z
- 近 30 天下载量：199548（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：1227（近 12 个月 1227 个）

## 中文简介

用于主题开发者工作流程的流动 CLI 插件 – dev 服务器, 推, 拉, init, 爬行, 比较

## 安装

```sh
npm install @fluid-app/fluid-cli-theme-dev
```

也可以使用：`pnpm add @fluid-app/fluid-cli-theme-dev`、`yarn add @fluid-app/fluid-cli-theme-dev`、`bun add @fluid-app/fluid-cli-theme-dev`

## README

# @fluid-app/fluid-cli-them-dev (英语)

Fluid CLI 主题开发插件. 添加数 `fluid theme` 用于本地 dev 服务器、推、拉、脚手架和 页码证据`crawl` 编号 : `compare`) (中文(简体) ).

## 安装

```bash
npm install -g @fluid-app/fluid-cli @fluid-app/fluid-cli-theme-dev
```

要求数 `@fluid-app/fluid-cli` 作为核心CLI.

## 认证

在使用任何主题命令前登录 :

```bash
fluid login
```

## 图标

### `fluid theme dev`

启动本地的 Dev 服务器, 以热重装代理您的仓库前端 :

```bash
fluid theme dev
```

Dev 服务器将:

1.  创建( 或重新使用) 一个孤立的发展主题
2.  保存未下载或重新加载其字节的图像 Kit URL 引用的二进制资产
3.  在当地保留可编辑源文件(Liquid、CSS、JS、SVG、JSON)
4.  上传一次新添加的二进制, 保存其 ImageKit URL 引用, 并删除其本地字节
5.  监视源文件更改并自动同步
6.  代理请求到 `{company}.fluid.app` 带有本地文件覆盖

对于被拉动的主题,新创建的dev主题是一个服务器侧引用克隆 的源头。 它保留了主题内容和DAM/ImageKit的引用, 因此初始的 Dev 启动不会从工作副本中重播所有资产 。 这个 CLI 保持发展主题的紧凑的当地指数 校验和版本。 后来的启动验证该版本, 比较本地文件 到缓存的 dev 状态, 只发送实际的更改而不下载 完整的远程资源索引。 网络编辑器写入, 更改了图像 Kit 显示、 丢失或格式错误的缓存或被中断的写入使 快捷键并返回到全远程比较。 设定 `FLUID_THEME_DEV_DISABLE_SHADOW_SYNC=1` 迫使这种比较成为紧急情况 倒转.

在拉出、推出或 dev写道. 视窗分离器在比较前实现正常化. 默认macOS 和 Windows 文件系统无法保存两种资源,所以继续会 替换一个路径并删除另一个路径.

| 旗帜 | 默认 | 说明 |
| --- | --- | --- |
| `--host <host>` | `127.0.0.1` | 本地服务器主机 |
| `--port <port>` | `9292` | 本地服务器端口 |
| `-t, --theme <name-or-id>` | 自动 | 使用特定的主题而不是 dev 主题 |
| `--live-reload <mode>` | `full-page` | 重新装入模式 : `full-page` 或者说 `off` |
| `--navigate` | 关 | 启动后打开浏览器导航器 |
| `--root <path>` | `.` | 主题根目录 |

### 会员地点

主题成员站点已退役. 成员地点现在与网址一起建造: `fluid sites` (单位:千美元)`fluid member-site`) (中文(简体) ). `fluid theme` 不再同步 `members_sites.json`, (中文(简体) ), `config/members_sites.json` 或者说 `members_page/**`,以及 `fluid theme dev` 没有 `/_members` 预览。 见 [成员地点(已退休)](https://npmcn.com/package/%40fluid-app/fluid-cli-theme-dev/#readme-member-sites-retired)。 。 。 .

### `fluid theme push`

上传本地主题文件到远程主题 :

```bash
fluid theme push                        # Interactive theme selection
fluid theme push --theme "My Theme"     # By name
fluid theme push --theme 42             # By ID
fluid theme push --publish              # Push and publish
fluid theme push --nodelete             # Keep remote files not present locally
fluid theme push --auto-baseline        # First push without a baseline: record
                                        # the server's current state as the
                                        # baseline, then push only local diffs
```

推入已存在的主题需要本地基线(记录如下: `pull`,或从校验和时代迁移 `.fluid-theme.json`) (中文(简体) ). 如果没有一个,推就拒绝,所以它不能无声地打乱服务器. `--auto-baseline` 相反,将服务器的当前状态记录为基线——没有修改本地文件,与服务器完全相同的文件没有被重新上载,并且只存在于服务器上的文件永远不会被删除——然后推出本地不同的内容. Mist桌面的一击Publishing使用此旗.

包含未解决的文件 `<<<<<<< / ======= / >>>>>>>` 冲突标记从未上传; 按下列表和退出( 带有机器可读) `FLUID_THEME_PUSH_BLOCKED code=conflict_markers files=…` 下行 `--auto-baseline`) (中文(简体) ).

### `fluid theme pull`

向本地目录下载远程主题 :

```bash
fluid theme pull                        # Interactive theme selection
fluid theme pull --theme "My Theme"     # By name or ID
fluid theme pull --nodelete             # Keep local files not present on remote
fluid theme pull --resolve remote       # Auto-resolve conflicts to the server's
                                        # side (or `--resolve local` to keep
                                        # yours) instead of writing markers
```

默认情况下, 相互冲突的编辑( 本地更改 ) _财务报告和审定财务报表_ 自上次同步以来,在服务器上用 git 风格冲突标记写出,供您解决。 为非交互式用途, `--resolve local` 保持你一方 每一个相冲突hunk和 `--resolve remote` 取取服务器的; 在任何自动解析覆盖本地内容之前, 预置的工作树会致力于主题的阴影历史(`.fluid-theme/repo`)所以被丢弃的一面仍然可以安息.

### `fluid theme widget`

自定义流体本地部件( Y)`{% section 'fluid://native/widgets/<key>' %}`(中文(简体) ) 通过主题本身的拷贝。 副本在每次替换部件 在主题中放置, 视觉构建器在部件时制作的同一份 已删除 :

```bash
fluid theme widget copy acct            # Make the copy and pull it into fluid_native_acct/ (asks first on the live theme)
fluid theme widget copy acct --yes      # Same, without the live-theme confirmation
fluid theme widget reset acct           # Delete the copy and its fluid_native_acct/ folder (asks first)
fluid theme widget reset acct --yes     # Same, without the confirmation
```

副本保留了Fluid原作的模板类型,因此被拉入 `sections/fluid_native_<key>/` 用于仍为区域并输入 `widgets/fluid_native_<key>/` 用于存储为部件. `reset` 删除 主题的任一类型的副本并删除两个文件夹.

两个命令都针对主题在 `.fluid-theme.json` 除非 `--theme <id>` 实值 通过了,然后运行一个普通 `fluid theme pull` 该主题的同步 基线匹配服务器。 推倒了其他任何改变 从上次拉起的主题.

在直播( 活动) 主题上, 复制件或重置更改成员看到的内容 这是制造的,所以 `copy` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}在它把复制品复制出来之前 `reset` 说 主题在它的确认中. `--yes` 跳过两个提示.

不创建 `sections/fluid_native_<key>/` 或者说 `widgets/fluid_native_<key>/` 用手:没有这种类型的拷贝,一推就使它成为一个简单的模板 替换什么,每个位置 总是渲染出Fluid的原作. `fluid theme push` 警告这些文件夹.

### `fluid theme init`

脚手架从基准模板中新建一个主题 :

```bash
fluid theme init my-theme
cd my-theme
fluid theme dev
```

### `fluid theme navigate`

交互选择一个路由并在浏览器中打开( 需要运行中的 Dev 服务器 ):

```bash
fluid theme navigate
```

### `fluid theme skills install`

复制捆绑的主题AI技能(如. `themes-review`进入当前目录 探员可以装上 默认为 `.agents/skills/`,用于代理人的工具中立公约 技能:

```bash
fluid theme skills install                      # → .agents/skills/
fluid theme skills install --dir .claude/skills # custom location
fluid theme skills install --force              # overwrite existing skills without prompting
```

除非确认覆盖( 或通过) , 现有技能将保持不变 `--force`) (中文(简体) ).

### `fluid theme crawl <url>`

通过 Fluid 的管理浏览器( JavaScript 已提供) 搜索一个公共页面并打印 JSON 带有它的Markdown,可选的HTML,以及主机截图 URL. Miss的经纪人负责这个 命令每个爬行.

```bash
fluid theme crawl https://example.com/                          # Markdown, main content only
fluid theme crawl https://example.com/ --format html --format screenshot
fluid theme crawl https://example.com/ \
  --viewport 1440x900 --full-page --quality 90 --no-main-content-only \
  --evidence .                                                  # durable page-clone bundle
fluid theme crawl https://example.com/ \
  --action '{"type":"click","selector":"#accept-cookies"}' \
  --action '{"type":"wait","milliseconds":1000}'               # act before the capture
```

| 选项 | 含义 |
| --- | --- |
| `--format <f>` | `markdown`, (中文(简体) ), `html`,或 `screenshot`; 可重复或逗号分隔. 默认 `markdown`,或所有三个 `--evidence` |
| `--viewport WxH` | 精确 CSS-像素取景口(含截图). 使用 `1440x900` 财务报告和审定财务报表 `390x844` 桌面/移动平价 |
| `--full-page` | 抓取完整的文档高度 |
| `--quality <1-100>` | 截图质量 |
| `--no-main-content-only` | 保持导航 公告栏和脚印 用它来克隆现场 |
| `--evidence <dir>` | 将证据保存在下面 `<dir>/.mist-desktop/source-baselines/`。要求 `--viewport` |
| `--action <json>` | 证据行走前的浏览器动作 : `{"type":"wait","milliseconds":N}` (最多1000个), `{"type":"click","selector":"…"}`,或 `{"type":"scroll","direction":"up|down"}`可重复,最多8个 |
| `--post-evidence-action <json>` | 证据行走后和最后截图前的动作,例如关闭了行走打开的抽屉. 还接受 `{"type":"dismiss","selector":"…","scope_selector":"…"}`边车记录的 需求 `--evidence` 财务报告和审定财务报表 `--full-page`可重复,最多8个 |
| `--direct` | 跳过 Fluid 的端点, 用你自己的来呼叫 Firecrawl `FIRECRAWL_API_KEY` |

`--evidence` 在布局雾中写入捆绑 `compare_preview_to_source` 读取,所以 雾或 `fluid theme compare` 可以比较: 全部截图, Markdown/HTML, 原始 HTML, 页面本身的 CSS, 以及 a `.page-evidence.json` 带有地标的侧车,计算样式,SHA-256散列车和收据. JSON 输出列出每个路径(`evidence.files`) (中文(简体) ). 内置内容上限约为 200KB,或保存完整文档时的16KB节选. 刮出的时间 60岁 `--evidence`,样式表恢复范围为 30 : 20多岁 两次下载都拒绝本地主机和私人网络地址.

**爬行所行之处.** CLI呼叫"Fluid"与你的"爬行"终点 `fluid login` 符号,所以不需要 Firecrawl 键 。 如果在您的 API 上没有部署终点 主机(HTTP 404)或未配置(HTTP 503),以及 `FIRECRAWL_API_KEY` 设定为 CLI 直接用那个钥匙回到Firecrawl 创建密钥于 [https://www.firecrawl.dev/app/api-keys 页面存档备份,存于互联网档案馆](https://www.firecrawl.dev/app/api-keys)。错误被打印为 JSON (单位:千美元)`{"ok": false, "error": {"code": …, "message": …}}`),和命令出 1.

### `fluid theme compare`

介绍当地 `fluid theme dev` 在爬行捆绑的确切取景口进行预览. 它印着 相同的带状像素 diff Mist的 `compare_preview_to_source` 报告:a `bands[]` 数组 和最坏的第一 `summary`并进行精确的复制和媒介均等检查.

```bash
fluid theme dev &                                   # serves http://127.0.0.1:9292
fluid theme compare --source .                      # newest "/" capture in ./.mist-desktop/source-baselines
fluid theme compare --source .mist-desktop/source-baselines/<file>.page-evidence.json \
  --route /collections/all --geometry diagnostic --media diagnostic
```

| 选项 | 默认 | 含义 |
| --- | --- | --- |
| `--source <path>` | (必须) | A 类 `.page-evidence.json` 侧车,其目录,或 `--evidence` 目录 |
| `--route <path>` | `/` | 本地路线 |
| `--source-route <path>` | `--route` | 当源路径名称不同时( 例如 ) `/en-us` 页:1 `/`(中文(简体) ) |
| `--url <url>` | `http://127.0.0.1:9292` | 运行预览的基础 URL |
| `--mode full|viewport` | `full` | 整页, 或仅取景端 |
| `--copy exact|diagnostic` | `exact` | `exact` 任何命令的复制不匹配失败 |
| `--geometry strict|diagnostic` | `strict` | `strict` 当文档高度差异超过5%时失败 |
| `--media strict|diagnostic` | `strict` | `strict` 在图像/视频对等差异上失败 |
| `--viewport WxH` |  | 选择此取景点时 `--source` 持有若干 |

命令拒绝混合抓取, 静默地调整大小, 失败的路径, 截取, 水平 溢出,未解决的介质,以及复制不匹配. 在拒绝时, `ok` 实值 `false` 编辑 1. 成功运行意味着有证据可用。 这并不意味着 页面通过视觉。 修复最差的乐队,然后再次比较. 本地抓获已保存 下级 `.mist-desktop/screenshots/`。 。 。 .

`compare` 需要一个无头浏览器。 Playwright 是一个可选的同伴依赖,所以 主题-dev 安装从不下载浏览器。 安装一次 :

```bash
npm i -g playwright && npx playwright install chromium
```

## 主题目录结构

有效的主题目录必须包含至少一个: `templates/`, (中文(简体) ), `assets/`, (中文(简体) ), `config/`,或资产参考表 `.fluid-assets.json`。 。 。 .

使用一个 `.fluidignore` 文件(语法与 `.gitignore`)将文件排除在同步之外.

### 远程二进制资产

`fluid theme pull` 保留图像、字体、视频和PDF等二进制资产 远程而不是下载到 `assets/`。他们的图像Kit URL 参考元数据记录于 `.fluid-assets.json`。CLI使用这个 当它开始一个 dev 主题或推向另一个主题时显示, 所以存在 `asset_url` 没有本地二进制副本,电话继续正常解决.

当开发者在开发期间添加新的二进制文件时 `fluid theme dev`、国家行动倡议 上传一次,将它的 ImageKit URL 引用记录在清单中,以及 在主题资源被保存后删除其本地字节 。 一会儿 `fluid theme push` 将相同的 ImageKit URL 写入选定目标主题 没有第二个二进制上传.

二等资产必须是下列企业的直接子女: `assets/` (例如, `assets/logo.png`; 嵌入式资产目录不支持主题 资源 API.

不添加 `.fluid-assets.json` 改为 `.fluidignore`; 已被排除在外 主题上传和文件监视。 把它交给主题来源 所以每个 开发者收到相同的远程资产引用.

## 成员地点(已退休)

主题成员网站( E)`members_sites.json` 在主题根或下 `config/`,以及 `members_page/<name>/` 模板)已退役. 构建成员 具有站点的站点 : `fluid sites` (单位:千美元)`fluid member-site`) (中文(简体) ).

`fluid theme` 在每个方向跳过这些文件并打印警告 命名他们:

-   `push`, (中文(简体) ), `dev` 财务报告和审定财务报表 `staging publish` 从不上传, 从不删除 Fluid的拷贝,所以已经在Fluid上的成员页一直为成员服务.
-   `pull` 财务报告和审定财务报表 `staging pull` 永远不要写; 本地副本被留下.
-   `staging compare` 既不宣布他们,又不认为他们与众不同.
-   `lint` 将它们列为警告,而不检查它们.

会员网站在Sites居住后,您可以删除本地文件.

## 原生部件

`{% section 'fluid://native/widgets/<key>', id: '…' %}` 设置流体所有 部件。 没有本地档案; `fluid theme lint` 接受已知密钥并警告 关于未知的。 设置一个新的本地部件需要公司 成员站点启用 .

要自定义部件,请使用 `POST /api/v202604/themes/<id>/native-widget-copies` 财务报告和审定财务报表 `{"native_widget_key": "<key>"}`。副本将替换每个部件 放在这个主题中,然后拉出它作为 `sections/fluid_native_<key>/index.liquid`。不要用手创建文件: a 手写 `sections/fluid_native_<key>` 是一个简单的区域,而不是 替换部件.

## 粘贴

已退休的模板类型`account_page`, (中文(简体) ), `members_dashboard` 财务报告和审定财务报表 `members_login`)不是主题文件:他们的文件夹从未上传, 已公布或列入清单.

### 当队友先发表时公布

`fluid theme staging publish` 发送它公布的每一个主题文件( 全部除外) 它跳过并列出路径,例如模板所附文件,所以 就会把每张支票的复印件放回去 来阻止它被摧毁 队友的工作是偶然的, 每一个成功的发布记录 中转 修订版及其公布的文件 `.fluid-theme/staging-baseline.json`。 。 。 . 下一次从同一目录发布时, 将运行与该记录进行比较 先说 从那时起,文件在运行时发生了变化,而且这次的检查有它们 不同的是,出版被拒绝 `staging_moved`,将这些文件命名为 以及目前的修订,并且没有任何改变:

```text
Staging has changes you don't have (revision 12). Publishing would replace them. Get those changes first, or publish with --force to replace them.
  - sections/hero_section/index.liquid
```

-   将它们的修改带入此检查并再次发布; 一旦复制 匹配的中转, 没有被替换 和检查通过.
-   `--replace-at <revision>` 故意替换它们,只在中转时 目前仍在修订中。 如果有人再次发表 同时,支票 运行并命名新文件。 烟雾 **无论如何替换** 用这个.
-   `--force` 替换任何修改.

路径是匹配的,但资源路径被拼出,所以大小写或 资源类型差异不会隐藏文件。 没有记录(新离职, 或文件被删除),没有什么可比较的,发布没有 检查。 与 `--json`拒绝的 `error.type` 实值 `staging_moved` 财务报告和审定财务报表 `error.paths` 列出文件.

### 带队友去换衣服

`fluid theme staging pull` 将其它文件写入此目录 自此目录上次发布以来, 已发布到中键, 所以下一个 出版时会携带他们的作品而不是被拒绝。 只写文件 此目录仍然和发布时一样; 您也更改了文件 保存并命名,绝不覆盖。 标出它自己的副本 菜单,所以从中取出的文件将每个文件放回菜单中 同一地点的目录名称( 匹配于后遗症) `members_sites.json` 菜单引用, 当双方仍然有一个; 文件 仍保留一个中转菜单。 退休成员网站文件 从来没有拿过。 当 目录然后匹配中转, 它的中转记录移动到当前 修订。 与 `--json` 它会打印 `revision`, (中文(简体) ), `taken`, (中文(简体) ), `kept` (每个单位) `reason`, (中文(简体) ), `matches`,以及 `verified` (在结束比较时作假) 无法完成,所以 `matches` (未经证实).

### 推动中场生活

`fluid theme staging promote` 拷贝确切的 装配在 现场主题,全部一次。 它列出它要写的文件并删除和询问 第一; 通过 `--yes` 以跳过问题( JSON 模式总是需要) `--yes`) (中文(简体) ). 这个 只有当现场主题没有改变的时候 才会推动 否则,它拒绝而不是掩盖这一变化。 图像和其他 二进制文件被复制到当前主题拥有的资产.

`fluid theme staging undo-promote` 原样放回现场主题 最新宣传,而现场主题 仍然服务于什么 申请晋升.

### 与中程比较

`fluid theme staging compare` 报告此目录文件与 主题的运行分支所服务的内容:内容改变的文件,文件 只有你才有 档案只有组装 它发送每个文件的SHA-256,从来没有 它的内容, 和改变什么。 出版至制作`fluid theme push`(中文(简体) ) 总是发送您的本地文件, 所以在启动时先比较 这不在这个退票, 例如一个队友的集合发布.

## 发展

对于在此单曲中工作的撰稿人:

```bash
pnpm --filter @fluid-app/fluid-cli-theme-dev build
node packages/cli/core/dist/bin/fluid.mjs theme --help
```

## 常见问题

### @fluid-app/fluid-cli-theme-dev 是什么？

用于主题开发者工作流程的流动 CLI 插件 – dev 服务器, 推, 拉, init, 爬行, 比较

### 如何安装 @fluid-app/fluid-cli-theme-dev？

在项目目录运行 npm install @fluid-app/fluid-cli-theme-dev，或使用 pnpm add / yarn add / bun add。

### @fluid-app/fluid-cli-theme-dev 支持 TypeScript 吗？

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

### @fluid-app/fluid-cli-theme-dev 支持 ESM 还是 CommonJS？

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

### @fluid-app/fluid-cli-theme-dev 需要什么版本的 Node\.js？

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

### @fluid-app/fluid-cli-theme-dev 可以商用吗？

@fluid-app/fluid-cli-theme-dev 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @fluid-app/fluid-cli-theme-dev 的下载量有多少？

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

### @fluid-app/fluid-cli-theme-dev 还在维护吗？

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

