当从旧 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 结构：
MVM mall 网上购物系统
下载
采用 php+mysql 数据库方式运行的强大网上商店系统，执行效率高速度快，支持多语言，模板和代码分离，轻松创建属于自己的个性化用户界面 v3.5更新： 1).进一步静态化了活动商品. 2).提供了一些重要UFT-8转换文件 3).修复了除了网银在线支付其它支付显示错误的问题. 4).修改了LOGO广告管理,增加LOGO链接后主页LOGO路径错误的问题 5).修改了公告无法发布的问题,可能是打压
/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」页面，所有迁移的页面将立即可见并支持编辑、排序与发布管理。
