cloudcannon-dev-server

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

The CloudCannon dev server

CloudCannon 开发服务器

cloudcannon dev

runs the real CloudCannon app against local files, with no login, on one origin. This skill starts the local editing loop and hands it to the user.

cloudcannon dev

会让真实的 CloudCannon 应用基于本地文件运行，无需登录，并使用单一 origin。此 skill 用于启动本地编辑循环，并将其交给用户。

The rule that costs the most sessions

最容易导致会话超时的规则

MUST rebuild the site after every change.
cloudcannon dev
never builds.

Why: the server serves a directory and syncs source files; it does not run the SSG.

--app-sync

carries an editor save to disk, so the field shows the new text — but the preview renders the built output, and nothing regenerated it. The user sees their edit in the field and the old page beside it, with no error anywhere.

每次更改后都必须重新构建站点。
cloudcannon dev
从不执行构建。

**原因：**服务器只会提供目录内容并同步源文件，不会运行 SSG。

--app-sync

会将编辑器中的保存操作同步到磁盘，因此字段会显示新文本——但预览渲染的是构建后的输出，而没有任何过程重新生成它。用户会看到字段中的新内容和旁边的旧页面，并且任何地方都不会报错。

The loop

编辑循环

cloudcannon configure detect-build-commands   # build command and output directory
<build the site>                              # see The build command, below
cloudcannon dev <output-dir> --port 10101     # leave running

Then tell them to open

http://localhost:10101

, and that Ctrl-C stops the server.

They do this	This happens
Change a source file in the editor	It reaches disk. Rebuild, then the preview updates itself
Change a source file on disk	Same — the server syncs it into the app. Rebuild, same result

The preview reloads itself whenever the output directory changes, so a rebuild in a second terminal closes the loop with nothing else running. See dev-server-api.md § Events.

Offer the user both routes and let them pick:

Route	What they do	Costs
Manual	Re-run the build after a batch of edits	Nothing. Rebuild when they want a fresh preview
Watched	Run watch-build.mjs	A full build per change

Default to manual. A watched rebuild after each save changes the output directory, and the preview then reloads the whole page. The editable regions' own in-place re-render is hidden behind that reload, so testing visual editing feels jarring. Manual also suits a slow build, or a post-build step that rewrites the whole output.

Offer watched when the user wants the preview to follow edits that editable regions don't re-render on their own: content edited in the source editor, data files, templates or styles.

cloudcannon configure detect-build-commands   # build command and output directory
<build the site>                              # see The build command, below
cloudcannon dev <output-dir> --port 10101     # leave running

然后告诉用户打开

http://localhost:10101

，并说明按 Ctrl-C 可停止服务器。

用户执行此操作	发生的情况
在编辑器中更改源文件	文件会同步到磁盘。重新构建后，预览会自动更新
在磁盘上更改源文件	同样如此——服务器会将更改同步到应用中。重新构建后，结果相同

每当输出目录发生变化时，预览都会自动重新加载。因此，只需在另一个终端中重新构建，无需运行其他任何内容即可完成闭环。参见 dev-server-api.md § Events。

向用户提供这两种方式，让用户自行选择：

方式	用户需要做什么	成本
手动	完成一批编辑后重新运行构建	无额外成本。用户需要时重新构建即可获得最新预览
监听式	运行 watch-build.mjs	每次更改都会执行一次完整构建

默认使用手动方式。每次保存后进行监听式重建会改变输出目录，预览随后会重新加载整个页面。可编辑区域自身的原地重渲染会被这次重载遮蔽，因此测试可视化编辑时体验会显得突兀。手动方式也适合构建速度较慢，或构建后步骤会重写整个输出目录的情况。

当用户希望预览跟随那些无法由可编辑区域自行重新渲染的编辑时，提供监听式方式，例如：源代码编辑器中的内容、数据文件、模板或样式。

The build command

构建命令

MUST detect the build with the CLI rather than by looking for config files.

cloudcannon configure detect-build-commands

is the product's own detection and covers every SSG the CLI knows. MUST NOT keep a second detection table anywhere in this skill; it would drift from the CLI's. Take the command it suggests (

npm run build

), not the bare SSG command — see setup.md § Build commands.

必须通过 CLI 检测构建，而不是查找配置文件。

cloudcannon configure detect-build-commands

是产品自身的检测机制，覆盖 CLI 已知的每一种 SSG。不得在此 skill 中维护第二套检测表，否则它会与 CLI 的检测结果产生偏差。采用 CLI 建议的命令（如

npm run build

），而不是 SSG 本身的命令——参见 setup.md § Build commands。

When to use

适用场景

The user wants to see and edit their site in CloudCannon before it is deployed anywhere
You just wrote editable regions, collections or inputs and the user needs to try them
The user reports a page as missing, blank or broken in CloudCannon, and you need to reproduce it locally against the real app

用户希望在部署到任何环境之前，通过 CloudCannon 查看和编辑站点
刚刚编写了可编辑区域、collections 或 inputs，用户需要试用
用户报告 CloudCannon 中的页面缺失、空白或损坏，需要基于真实应用在本地复现问题

When not to use

不适用场景

Authoring collections, inputs or structures — that is
```
cloudcannon-configuration
```
. This skill serves the result; it does not decide it.
Authoring editable regions — that is
```
cloudcannon-visual-editing
```
.
Checking that a site's output is correct — whether URLs match the collection config, whether pages are orphaned. This skill starts a server; it does not grade the site.
Driving the editor in a browser — clicking regions, dumping inputs, screenshotting. Ask the user to look.
Final sign-off. Local CloudCannon has no real save-to-git, no build pipeline and no permissions. A human still confirms on the hosted site.
Testing hosted-only behaviour. The local app isn't told the SSG, so SSG-specific rules don't apply locally — a Hugo site's config files show in a collection locally even without
```
include_developer_files
```
(Site config as data). Creating new files isn't a faithful test either: an unsaved new entry carries a temporary flat name.

编写 collections、inputs 或结构——应使用
```
cloudcannon-configuration
```
。此 skill 用于处理结果，不负责决定如何编写。
编写可编辑区域——应使用
```
cloudcannon-visual-editing
```
。
检查站点输出是否正确——例如 URL 是否与 collection 配置匹配、是否存在孤立页面。此 skill 用于启动服务器，不会评估站点。
在浏览器中操作编辑器——例如点击区域、提取 inputs 或截屏。应让用户自行查看。
**最终验收。**本地 CloudCannon 没有真正的 save-to-git、构建流水线或权限机制。最终仍需由用户在托管站点上确认。
**测试仅托管环境才有的行为。**本地应用不会获知 SSG 类型，因此 SSG 专属规则在本地不适用——即使没有
```
include_developer_files
```
，Hugo 站点的配置文件在本地也会显示为 collection（参见 Site config as data）。创建新文件也不是忠实的测试，因为未保存的新条目会带有临时的扁平名称。

File	Covers
setup.md	Prerequisites, what `cloudcannon dev` does and does not do, the build, ports
dev-server-api.md	The `/__api` surface — every route and the event stream
troubleshooting.md	Symptom → cause → fix
scripts/README.md	`watch-build.mjs` and its flags

文件	涵盖内容
setup.md	前置条件、 `cloudcannon dev` 的作用与限制、构建、端口
dev-server-api.md	`/__api` 接口——所有路由和事件流
troubleshooting.md	症状 → 原因 → 修复方法
scripts/README.md	`watch-build.mjs` 及其参数

Common mistakes

常见错误

Excuse	Reality
" `cloudcannon dev` is running, so the loop works."	It serves a directory and nothing else. Until something rebuilds, the preview is whatever was built last.
"The editor saved but the page did not change."	Expected. Rebuild — and with a watcher, wait for the build to finish.
"I will open `/index.html` to see the built page."	`/` and `/index.html` both serve the CloudCannon app. The built homepage is at `/__output/index.html` .
" `/about/` returns 500, the server is broken."	The server has no directory index. Request `/about/index.html` .
"Port 10101 answers, so my site is up."	It proves a dev server is there, not that it is yours. Serve on a port you chose and know is free.
"The diff is huge, something corrupted it."	CloudCannon reserialises the whole frontmatter on save. Diff the field you changed.

误解	实际情况
“ `cloudcannon dev` 正在运行，所以编辑循环可以正常工作。”	它只会提供目录内容，不会执行其他操作。在重新构建之前，预览始终是上一次构建的结果。
“编辑器已经保存，但页面没有变化。”	这是预期现象。请重新构建——使用 watcher 时，还要等待构建完成。
“我会打开 `/index.html` 来查看构建后的页面。”	`/` 和 `/index.html` 提供的都是 CloudCannon 应用。构建后的主页位于 `/__output/index.html` 。
“ `/about/` 返回 500，说明服务器坏了。”	服务器没有目录索引。请请求 `/about/index.html` 。
“端口 10101 有响应，所以我的站点已经启动。”	这只能证明存在一个开发服务器，不能证明它属于你。请选择一个明确且确认空闲的端口。
“差异非常大，一定是内容损坏了。”	CloudCannon 在保存时会重新序列化整个 frontmatter。请只对比你更改的字段。