当从旧 octobercms 项目迁移静态页面模板时，若页面能正常访问但未出现在后台「static pages」列表中，通常是因为遗漏了关键的 `static-pages.yaml` 元数据文件。该文件负责向系统注册页面路径与配置，缺失将导致页面不可见、不可编辑、url 被锁定。
在 OctoberCMS 中，静态页面插件（RainLab.Pages）采用“双文件注册机制”：
- 页面内容存于 .htm 模板文件（如 pages/home.htm）；
- 页面元信息（URL、标题、是否启用、排序等）则由 static-pages.yaml 统一声明。
即使 .htm 文件已正确复制到新主题的 pages/ 目录下，若 /themes/yourTheme/meta/static-pages.yaml 文件缺失或未同步，后台将无法识别这些页面——表现为：
✅ 页面可通过 URL 正常访问（因 Twig 渲染器仍可解析 .htm）；
❌ 后台「Static Pages」列表为空或仅显示默认页面；
❌ 尝试新建同 URL（如 /）的页面时提示“URL 已被占用”。
✅ 正确操作步骤如下：
- 定位旧主题目录：/themes/oldTheme/meta/static-pages.yaml；
- 将该 YAML 文件完整复制至新主题对应路径：/themes/newTheme/meta/static-pages.yaml；
- 确保文件编码为 UTF-8（无 BOM），且 YAML 格式合法（推荐用 YAML Lint 校验）；
- 清除缓存：在后台点击 System → Caches → Clear all caches，或执行命令：
php artisan cache:clear php artisan october:util compile
? 示例 static-pages.yaml 结构：
/home.htm:
url: /
title: Home Page
is_hidden: false
layout: default
description: Main landing page
/about.htm:
url: /about
title: About Us
is_hidden: false
layout: default⚠️ 注意事项：
- 文件路径必须严格匹配 .htm 文件在 pages/ 目录下的相对路径（如 pages/contact.htm 对应 YAML 中的 contact.htm）；
- 若使用子目录（如 pages/blog/post.htm），YAML 键名应为 blog/post.htm；
- 修改 static-pages.yaml 后必须清缓存，否则变更不生效；
- 不建议手动编辑 YAML 文件中的 url 字段为已存在的路由（如 /），除非确认无冲突；
- 新建页面时，插件会自动更新此文件；迁移时请确保其与 .htm 文件版本一致。
完成上述步骤后，刷新后台「Static Pages」页面，所有迁移的页面将立即可见并支持编辑、排序与发布管理。
