cloudcannon-dev-server

CloudCannon 开发服务器

cloudcannon dev 会在同一个源上运行真实的 CloudCannon 应用并使用本地文件，无需登录。此技能会启动本地编辑循环，并将其交给用户。

最容易导致会话失败的规则

必须在每次更改后重新构建网站。cloudcannon dev 从不构建。

**原因：**服务器会提供一个目录并同步源文件；它不会运行 SSG。--app-sync 会将编辑器中的保存操作同步到磁盘，因此字段会显示新文本——但预览渲染的是构建后的输出，而没有任何东西重新生成它。用户会在字段中看到自己的编辑，而旁边的页面仍是旧内容，且没有任何错误提示。

循环流程

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 § 事件。

向用户提供两种方式，由他们选择：

方式	用户的操作	代价
手动	批量编辑后重新运行构建	没有。想要查看最新预览时再重新构建
监视	运行 watch-build.mjs	每次更改都会完整构建一次

默认采用手动方式。每次保存后监视重建都会更改输出目录，随后预览会重新加载整个页面。可编辑区域自身的局部重新渲染会被这次重新加载遮住，因此测试可视化编辑时会感觉很突兀。手动方式也适合构建较慢，或构建后步骤会重写整个输出的情况。

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

构建命令

必须通过 CLI 检测构建命令，而不是查找配置文件。cloudcannon configure detect-build-commands 是产品自身的检测功能，涵盖 CLI 所知的所有 SSG。不得在此技能的任何位置维护第二张检测表；它会与 CLI 的检测结果不一致。使用它建议的命令（npm run build），而不是裸的 SSG 命令——请参阅 setup.md § 构建命令。

适用情况

• 用户希望在网站部署到任何地方之前，在 CloudCannon 中查看并编辑网站
• 你刚编写了可编辑区域、集合或输入项，用户需要试用
• 用户报告 CloudCannon 中的页面缺失、空白或损坏，而你需要在本地真实应用中复现问题

何时不应使用

• 编写集合、输入项或结构——这属于 cloudcannon-configuration 的职责。此技能负责呈现结果，而不是决定结果。
• 编写可编辑区域——这属于 cloudcannon-visual-editing 的职责。
• 检查网站输出是否正确——例如 URL 是否与集合配置匹配、页面是否成为孤立页面。此技能会启动服务器，但不会检查网站是否合格。
• 在浏览器中操作编辑器——点击区域、转储输入项、截屏。请让用户自行查看。
• **最终签核。**本地 CloudCannon 无法真正保存到 Git，没有构建流水线，也没有权限管理。仍需由人工在托管网站上确认。
• **测试仅限托管环境的行为。**本地应用不会获知 SSG，因此 SSG 特定规则在本地不适用——即使没有 include_developer_files，Hugo 网站的配置文件也会在本地显示于集合中（将网站配置视为数据）。创建新文件也不是忠实的测试：未保存的新条目会带有临时的扁平名称。

目录

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

常见错误

借口	实际情况
“cloudcannon dev 正在运行，所以工作流程正常。”	它只会提供一个目录，除此之外什么也不做。在有内容触发重新构建之前，预览显示的都是上次构建的结果。
“编辑器已保存，但页面没有变化。”	这是预期行为。请重新构建；如果使用监视器，请等待构建完成。
“我会打开 /index.html 查看构建后的页面。”	/ 和 /index.html 都会提供 CloudCannon 应用。构建后的首页位于 /__output/index.html。
“/about/ 返回 500，服务器坏了。”	服务器没有目录索引。请请求 /about/index.html。
“10101 端口有响应，所以我的网站已启动。”	这只能证明有开发服务器在运行，不能证明那是你的服务器。请使用自己选择且确认空闲的端口提供服务。
“差异太大了，一定是出了问题。”	CloudCannon 保存时会重新序列化整个 frontmatter。请比较你修改的字段。