常见问题
安装与环境
是否需要 Composer？
不需要。框架内核以完整源码的形式放在 flight/ 目录里，业务代码用一个简单的 PSR-4 风格自动加载器映射 App\ 命名空间到 app/ 目录。仓库里没有 composer.json，也没有 vendor/。
后台用了 Tailwind、htmx 和 SunEditor，为什么说没有构建步骤？
这些都是运行时引入的本地静态文件，放在 public/assets/ 下由 Web 服务器直接返回，不经过打包器。后台其余交互使用严格 CSP 兼容的原生 JavaScript；前台主题是纯 PHP 模板加手写 CSS，连运行时框架都没有。
首页正常，其他页面返回 404？
改写规则没生效。Apache 要确认开了 mod_rewrite 且虚拟主机是 AllowOverride All；Nginx 要确认写了 try_files $uri $uri/ /index.php?$query_string。
提示未安装、一直跳转到 install.php？
说明 config/config.php 或安装标记文件不存在。如果是从别的站点拷过来的目录，不要复制对方的 config/ 和 storage/，重新跑一次安装器。
SQLite 是否适合生产环境？
可以跑，但只建议用于内容量小、写入并发低的站点。SQLite 写操作会锁整库。默认推荐 MySQL 5.7 / 8.0。
主题与模板
如何制作自己的主题？
复制 public/themes/default/ 到 public/themes/你的slug/，改 theme.json 里的名字和 slug，然后改模板与 assets/。目录名就是主题 slug。切换用后台「主题管理」，或命令行 php bin/set-theme.php 你的slug。
主题必须包含哪些文件？
layout.php、home.php、list.php、detail.php、page.php、contact.php、search.php 和 theme.json。模板文件缺失时系统会写日志并直接报错，不会静默退回默认主题——这样问题能被立刻发现。
单页想要一套自定义排版和可配置字段？
在主题的 pages.php 里声明一个模板，指明 file（对应的模板文件名）和 fields。后台编辑该单页时选中这个模板，就会自动出现对应的表单项，模板里从 $fields 读取。支持文本、多行文本、富文本、图片、数字、视频、下拉，以及可增删排序的重复行。
改了主题 CSS，浏览器还是旧的？
不用手动清缓存。Theme::url() 会按文件修改时间自动给资源 URL 加版本号。如果确实没变，检查一下模板里是不是硬编码了资源路径，而不是走 Theme::url()。
模板里能不能直接查数据库？
可以调用 App\Models\* 的读方法（比如按栏目取内容列表）。但不要在模板里做写操作，也不要在主题里另写一套上传逻辑——图片一律引用媒体库 URL。
多语言
栏目要不要每种语言各建一遍？
不用。栏目结构是语言无关的：一套栏目树，译名存在栏目自身的多语言字段里，菜单项同理。只有内容是按语言一行行存的，同一篇的各语言版本用翻译组关联起来。
URL 长什么样？
默认语言不带前缀，其它语言带语言前缀，例如中文 /news、英文 /en/news。当前语言查不到内容时会回退到默认语言渲染，这类页面会自动标记为不索引，避免 canonical 和 hreflang 自相矛盾。
默认语言能停用吗？
不能，后台会拦住。默认语言一旦停用，全站链接的前缀规则和 canonical 都会错乱。
内容与权限
删掉的内容还能找回来吗？
能。删除是移入回收站，可以恢复；此外内容有修订历史，可以回滚到之前的版本。后台的写操作会记入审计日志。
角色权限怎么配？
角色对应一份能力清单，可以在后台「角色权限」中配置。控制器声明访问所需能力，并由基类在请求进入时统一校验。admin 角色始终拥有全部能力，不能通过角色配置移除。
有没有对外的 JSON API？
目前没有。这是一套服务端渲染系统，/admin/* 是后台界面的内部接口，不适合当作第三方 API 使用。需要给小程序或 App 供数时，应当另建带版本号的接口，用独立的认证、限流和错误格式。
运维
备份怎么做？
php bin/cms.php backup 导出数据库；恢复用 php bin/cms.php restore。导出是流式写文件的，内存占用与库的大小无关。注意 MySQL 的结构变更会隐式提交，恢复过程不是原子的，操作前请自行准备好可回滚的快照。
日志会一直涨吗？
php bin/cms.php log:prune 清理过期日志与访问记录，建议挂到计划任务里定期执行。
升级要注意什么？
框架与 CMS 核心作为同一个经过测试的发行版本一起更新，不要单独去追框架的上游最新版，也不要手工覆盖实例数据。先用 php bin/cms.php upgrade <安装包.tar.gz> --dry-run 预检，再执行正式升级；升级器会自行迁移并做健康检查。