最有效的方式是禁用CSS类名混淆或白名单关键类名；问题根源是构建后类名被随机替换导致querySelector找不到元素，需通过开发者工具确认，并在Vite、Webpack或Tailwind中配置排除规则，或改用data属性、结构定位等更健壮方案。
直接在打包配置中禁用 CSS 类名混淆，或明确保留关键类名不被重命名，是解决 querySelector 失效最有效的方式。这类问题不是 DOM 查找逻辑出错，而是查找目标本身在构建后已不存在——原类名被替换成随机字符串，而 JavaScript 里写的还是旧名字，自然找不到元素。
确认是否真由类名混淆引起
先打开生产环境页面，按 F12 打开开发者工具，在 Elements 面板中手动搜索你代码里用到的类名（比如 .user-card）。如果页面实际渲染的元素上写的是 .a2x9k 这类短名，而你的 JS 仍写 document.querySelector('.user-card')，那就坐实了是混淆导致的断连。
注意：有些混淆工具（如 Tailwind 的 next-css-obfuscator）会混淆伪类前缀（hover:underline → ho_8s2l）、通配选择器（*:justify-center）或自定义参数类（z-[999]），这些也需一并检查是否被误改。
在构建工具中关闭或白名单关键类名
不同工具配置位置不同，但思路一致：不让混淆器动你 JS 里依赖的那些类名。
立即学习“前端免费学习笔记（深入）”；
-
Vite + postcss：在
postcss.config.js中使用postcss-safe-parser或配合cssnano的safe模式，并设置svgo: false和reduceIdents: false；更稳妥的是用cssnano-preset-default的ignore: ['user-card', 'devArticle', 'project-tile']显式保留 -
Webpack + css-loader：若启用了 CSS Modules（
modules: true），默认类名就是哈希化的，此时 JS 中应改用import styles from './Button.module.css'，再通过styles['primary-btn']获取真实类名，而非硬编码字符串 -
Tailwind + obfuscation 插件：在插件配置中添加
exclude: [/^user-/, /^dev/, /^project-/]正则排除，或直接禁用混淆（enabled: false）——除非你有强混淆合规要求，否则多数场景无需混淆类名
重构 JS 查找逻辑，避开硬编码类名
与其让构建工具“别改名字”，不如让 JS “不依赖名字”。这是更健壮、长期可维护的做法。
- 用 data 属性替代 class：把
<div class="devArticle">改成<div data-role="dev-article">，JS 改为document.querySelector('[data-role="dev-article"]')—— data 属性默认不会被任何 CSS 混淆工具处理 - 用 结构关系定位：例如博客文章常嵌套在
<main>下的首个<article>，可用document.querySelector('main > article:first-of-type')，不依赖类名 - 对多页特有元素，先判断容器是否存在再操作：避免
querySelectorAll('.devArticle')在非博客页报错，可加一层守卫if (document.body.classList.contains('page-blog')) { ... }
补充：避免混淆与 JS 交互的 CSS 变量和动画名
如果 JS 通过 getComputedStyle(el).getPropertyValue('--theme-color') 读取 CSS 变量，或用 el.getAnimations().find(a => a.effect?.getTarget() === el) 控制动画，也要确保这些变量名（--theme-color）、动画名（@keyframes fade-in）未被 PostCSS 插件或 esbuild 的 CSS 提取阶段重命名。可在相关插件配置中加入 preserve: ['--theme-*', 'fade-*'] 类似规则。
