准备阶段：定位与备份以确保安全移除
MODX 移除旧菜单项的完整教程与实操要点 在正式操作前，先进行清晰的定位与充分的备份。此阶段的目标是明确哪些菜单项需要移除、评估对管理员界面的影响，以及确保有回滚方案以应对意外情况。
第一步是对现有管理员菜单进行扫描，记录需要移除的项的名称与层级关系。正确的定位可以避免误删正常功能，同时为后续的数据库或代码层清理提供明确依据。
另一个关键环节是备份策略。对数据库和相关配置进行备份，包括 modx_menu 表（以及可能影响的缓存、菜单缓存等）以及自定义插件的代码。没有回滚机制的变动在生产环境中风险较高。
确定要移除的菜单项
在确定要移除的项时，优先列出“永远不再使用”的菜单条目，例如那些属于旧版本或已废弃的功能模块。保持文档化的清单将有助于日后Q&A与故障排查。
同时，注意不同环境的差异，例如开发环境与生产环境的菜单项可能不同。对照环境差异，逐项验证再执行删除，避免误伤当前活跃的工作流。
备份与回滚策略
在执行任何删除操作前，确保你可以快速还原。定期备份数据库快照、MODX 配置与菜单缓存，并记录变动时间线，方便在出现显示错误时快速回滚。
若需要回滚，可以通过加载备份、重新导入 modx_menu 表数据，或在插件中实现一个“启用/禁用菜单项”的开关机制来快速恢复。回滚流程应在测试环境中先验证再落地到生产。
直接数据库操作：清理旧菜单项的步骤与要点
定位目标表与字段
在 MODX 的默认配置中，管理端的菜单数据通常存储在 modx_menu 表（前缀为你站点的 table_prefix，实际表名如 prefix_menu）。确认前缀避免误删其他表，这是直接清理的基础。
表中的关键字段通常包括 text（菜单文本）、parent（父项ID）以及 controller/action（跳转目标）。
执行删除操作的SQL示例
下面的示例演示如何直接在数据库层删除文本匹配的旧菜单项。请在执行前替换前缀并确保已备份。
-- 将 modx_ 替换为你的前缀
DELETE FROM modx_menu
WHERE text LIKE '%旧项%';
如果你只想删除某个父级下的子项，可以增加 parent 条件，例如删除父项为 12 的所有文本包含“旧项”的子项。精确条件可降低误删风险。
使用 XPDO API 的清理方式
通过 MODX 的 API，在代码中执行清理可以避免直接改动数据库的风险，并且便于在插件中动态控制。以下示例演示移除文本匹配的菜单项对象。
getOption('db_prefix', null, 'modx_'); // 一般为 modx_，如有自定义前缀请调整$criteria = array('text:LIKE' => '%旧项%');
$menus = $modx->getCollection('modMenu', $criteria);foreach ($menus as $menu) {// 直接删除符合条件的菜单项$menu->remove();
}
echo '已移除匹配项的菜单项数量：' . count($menus);
?>
使用 API 的好处在于可复用性与可控性，并且可以与缓存清理逻辑结合，确保界面同步更新。
通过事件钩子实现动态过滤：无痛隐藏旧菜单项的方案
创建插件并注册 OnManagerMenuBeforeRender
为了在运行时按照条件隐藏旧菜单项，可以通过创建一个管理插件，在 OnManagerMenuBeforeRender 事件点进行处理。动态过滤的优点是无需修改数据库结构，且可在不同环境灵活配置。
实现要点包括：加载事件、获取当前菜单结构、根据规则删除或屏蔽特定菜单项、刷新缓存以确保界面即时生效。
示例：简单的动态过滤实现流程
下面的伪代码展示了思路：在 OnManagerMenuBeforeRender 事件中，遍历顶层菜单，若发现文本匹配名单中的项，调用 remove() 将其从渲染树中移除；需要时也递归处理子项。
getCollection('modMenu', array('parent' => 0)); // 顶层菜单
foreach ($menus as $menu) {if (in_array($menu->get('text'), $hideList)) {$menu->remove();continue;}// 递归处理子菜单（如有）$children = $menu->getMany('Children'); // 伪代码，实际需按 MODX API 调整foreach ($children as $child) {if (in_array($child->get('text'), $hideList)) {$child->remove();}}
}
?>
在实际应用中，请结合你所用 MODX 版本的 API 文档调整实现细节，并务必在测试环境中验证可用性与稳定性。
分环境与多站点场景下的实操要点
多前缀表名与多环境的处理
在多站点或多环境部署时，前缀可能不同，务必在脚本中获取正确的 table_prefix，避免跨站点修改数据。通过 MODX 的 db_prefix 配置项读取前缀是推荐做法。
如果你的站点存在多个环境（如 dev、stg、prod），建议使用一个统一的开关或环境变量来控制何时应用删除操作，避免直接在生产环境执行非预期的删除。
缓存与菜单渲染的同步
对菜单项的删除往往需要清理相关缓存，否则页面渲染时仍会显示已删除项。删除后务必执行缓存刷新或清理，确保管理员端界面与数据一致。
排错与维护要点：确保新旧菜单的稳定切换
为什么旧菜单项仍然显示？诊断路径
常见原因包括：缓存未清理、删除操作未实际提交、或菜单的渲染逻辑被其他插件覆盖。首先检查浏览器端缓存，其次在服务端尝试直接查询 modx_menu 表以确认数据是否已被删除。
另外，若使用插件动态隐藏菜单，请检查 OnManagerMenuBeforeRender 的执行顺序，确保自定义逻辑在渲染前生效，避免被后续插件覆盖。
缓存刷新与版本控制
在完成删除或过滤后，做一次强缓存清理，确保用户看到的是最新的菜单结构。记录每一次变更的时间与版本号，方便后续回滚或对比。
回滚测试与回退策略
建义在测试环境中进行回滚演练：通过还原备份、重新启用被删除的菜单项，验证功能与权限是否正常。确保回滚路径与回滚点清晰可用，以降低生产环境风险。
