querySelector 不会因语法错误崩溃，但返回 null 后调用方法会抛 TypeError；需检查选择器是否匹配、验证返回值、注意大小写与转义、确保 DOM 加载完成，并可用 querySelectorAll 辅助诊断。

querySelector 本身不会因选择器语法错误而直接崩溃，但会返回 null，后续若对 null 调用方法（如 .addEventListener()、.innerText）就会抛出 TypeError: Cannot read property 'xxx' of null —— 这才是实际“崩溃”的根源。排查关键在于区分“选择失败”和“使用失败”。

检查选择器是否匹配到元素

在调用 querySelector 后立即验证返回值：

• 加 console.log(document.querySelector('.my-class')) 看是否为 null 或 undefined
• 用条件判断兜底，避免后续操作：
  

  const el = document.querySelector('#header');<br>if (!el) { console.warn('未找到 #header 元素'); return; }<br>el.addEventListener('click', handler);

• 注意：CSS 选择器对大小写、空格、特殊字符敏感，比如 .btn-primary 和 .btn -primary（中间多空格）完全不等价

验证选择器语法合法性

浏览器控制台可快速测试：

java-api-doc-generator

分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。

下载

• 在 DevTools 的 Console 中直接输入 document.querySelector('你的选择器')，观察是否报 SyntaxError
• 常见语法错误包括：
    • 缺少引号包裹（如 querySelector(.class) ❌，应为 querySelector('.class') ✅）
    • 错误转义（如 ID 含点号 id="user.name"，需写成 querySelector('#user\.name')）
    • 使用了不支持的伪类（如 :has() 在部分旧版浏览器中无效，但不会语法报错，只返回 null）

确认 DOM 加载时机

querySelector 找不到元素，90% 是因为执行太早：

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

• 脚本放在 中且未加 defer 或 DOMContentLoaded 监听 → 此时 DOM 树尚未构建，必然返回 null
• 解决方案：
    • 把 <script></script> 标签移到 前
    • 或包装在 document.addEventListener('DOMContentLoaded', () => { ... }) 中
    • 或使用 async + defer（注意语义差异）

用 querySelectorAll + length 辅助诊断

当不确定是否该有多个匹配项时，改用 querySelectorAll 更直观：

• const list = document.querySelectorAll('.item[data-status="active"]');
• console.log(`共找到 ${list.length} 个匹配元素`);
• 如果 length === 0，说明选择器逻辑或 DOM 状态有问题，而非语法错误
• 还能用 Array.from(list).forEach(el => console.log(el.outerHTML)) 快速查看实际匹配到什么