Drupal调试钩子需满足四大前提：模块已启用、缓存已清除、钩子函数命名严格规范（mymodule_hookname）、调用发生在完整HTTP请求周期内；否则钩子不注册、不触发、无响应。

Drupal 不是“学 PHP 就能直接上手”的 CMS，它有自己的运行契约和抽象层级。想写模块、改路由、调试钩子，光会 echo 或 foreach 不够——得理解它怎么加载代码、怎么触发钩子、怎么管理请求生命周期。

drupal_set_message() 不显示？别 debug 函数本身

这不是代码写错了，而是你没在正确的上下文中调用它。drupal_set_message() 依赖完整的 HTTP 请求响应周期，只在页面渲染阶段生效。在 PhpStorm 里右键 Run 一个 .php 文件、或在 CLI 下执行模块函数，消息永远不会出现。

• 必须通过浏览器访问真实 URL（比如 /admin/config 或你自定义的路径）才能触发
• 确保模块已启用：drush pm:status mymodule 或后台 /admin/modules 确认状态为 enabled
• 清空缓存：drush cr，否则钩子注册、路由定义可能未加载
• 检查是否在 AJAX 回调里误用了它——AJAX 响应默认不渲染消息区域，得手动加 ['#attached']['library'][] = 'core/drupal.dialog.ajax' 并在前端处理

hook_form_alter() 断点不进？先确认钩子有没有被发现

断点“失效”大概率是钩子根本没注册成功。Drupal 在内核启动时扫描所有启用模块的 .module 文件，按命名规则提取函数名，再匹配到对应表单 ID。任意一环断掉，函数就不会被调用。

• 函数名必须严格为 mymodule_form_FORM_ID_alter() 或 mymodule_form_alter()，大小写、下划线、模块名拼写全要一致
• FORM_ID 得是目标表单的真实 ID，不是路径。查法：在表单页面开启开发者工具 → 查看源码找 id="edit-xxx" 或用 ksm($form)（需 Devel 模块）打印
• 模块必须放在 modules/custom/mymodule/ 下，且 mymodule.info.yml 中 core_version_requirement 匹配当前 Drupal 版本（如 ^10）
• 别忘了 drush cr —— 钩子列表是缓存的，改完函数名不清理缓存，旧注册信息还在

自定义路由 404？不是代码问题，是 web 目录或重写没配对

Drupal 8+ 的路由系统完全依赖 Apache/Nginx 的 URL 重写能力。如果访问 /hello 直接返回 404，90% 是 Web 服务器没把请求交给 index.php 处理。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

• Web 根目录必须指向 web/ 子目录（不是项目根），否则 .htaccess 不生效、autoload.php 找不到
• Apache 必须启用 mod_rewrite，且对应 <directory></directory> 块中 AllowOverride 设为 All（不是 None 或 FileInfo）
• Nginx 用户注意：不能照搬 Apache 的 .htaccess 规则，得手动配置 try_files $uri /index.php?$query_string;
• 路由文件 mymodule.routing.yml 必须放在模块根目录，不能放错位置；_controller 的命名空间必须完整，比如 \Drupal\mymodule\Controller\HelloController::response

IDE 补全找不到 db_query() 或 entity_load()？补全不是靠猜，是靠路径索引

PhpStorm 默认不认识 Drupal 函数，不是插件没装，而是它根本不知道 Drupal 核心代码在哪。没有代码路径，就没有语义分析，自然没有补全、跳转或类型提示。

立即学习“PHP免费学习笔记（深入）”；

• 装好官方 Drupal Support 插件后，必须去 Settings > Languages & Frameworks > PHP > Frameworks > Drupal 手动填入核心路径，例如 /path/to/drupal/web/core
• 如果是 Composer 项目，确保 vendor/autoload.php 已加到 Include Paths（Settings > PHP > Include Paths）
• db_query() 在 Drupal 9+ 已废弃，补全不出来是正常的——该用 \Drupal::database()->select() 或注入 DatabaseConnection
• entity_load() 同样废弃，应改用 \Drupal::entityTypeManager()->getStorage('node')->load(123)，补全依赖正确的 use 声明和命名空间

真正卡住人的从来不是语法，而是 Drupal 把“谁在什么时候加载什么代码”这件事藏得太深。每次改完东西没反应，先问：缓存清了没？路径指对了没？模块启用了没？请求走的是不是完整 HTTP 生命周期？把这四个问题挨个过一遍，比翻十页文档更快。