容器查询插件必须手动安装，不能靠 Tailwind v3.4 自带；需启用 experimental.containerQueries 开关、安装 @tailwindcss/container-queries 插件、将 @container 规则置于 @layer 内、HTML 元素显式添加 @container 类，四者缺一不可。
容器查询插件必须手动安装，不能靠 Tailwind v3.4 自带
Tailwind v3.4 虽然引入了 experimental.containerQueries 开关，但它本身不包含容器查询逻辑——所有解析和变体生成都由 @tailwindcss/container-queries 插件完成。没装这个包，哪怕开了实验开关也完全无效。
常见错误现象：@md:text-lg 类写在 HTML 里，DevTools 中查不到对应 CSS 规则，控制台也无报错。
- 执行
npm install -D @tailwindcss/container-queries（注意是-D，开发依赖） - 确保插件版本与 Tailwind 兼容：v3.4.17+ 对应插件 v0.3.0+（截至 2026 年 10 月，最新稳定版为 v0.3.2）
- TypeScript 项目需确认
@types/node已安装，否则require()可能导致构建失败
tailwind.config.js 的配置位置和写法很关键
experimental.containerQueries: true 必须直接写在配置对象顶层，不能嵌套进 theme、plugins 或其他字段里。PostCSS 插件链在启动时只读根级 experimental 字段，嵌套即忽略。
正确写法示例：
立即学习“前端免费学习笔记（深入）”；
module.exports = {
experimental: { containerQueries: true },
plugins: [
require('@tailwindcss/container-queries'),
],
// 其他配置...
}
- 如果用了自定义
theme.container（比如改了container-name），要确认没覆盖整个container对象，否则可能让@container类失效 - 插件
require()必须出现在plugins数组中，且顺序无关紧要；但若同时用其他插件（如@tailwindcss/typography），建议保持插件声明清晰可读
@container 规则必须包裹在 @layer 内，否则静默丢弃
所有 @container 块（包括命名容器如 @container card 和匿名查询）必须放在 @layer utilities 或 @layer components 里。Tailwind 的 PostCSS 插件只扫描这些 layer 下的规则，外面写的全部跳过，不报错也不生成 CSS。
错误写法（样式不会生成）：
@container (min-width: 32rem) {
.card-title { font-size: 1.25rem; }
}
正确写法：
@layer utilities {
@container (min-width: 32rem) {
.card-title { font-size: 1.25rem; }
}
}
- 命名容器（如
@container main）同样适用此规则，必须包在@layer里 - 如果用的是变体语法（如
@lg:font-bold），它底层仍依赖@layer中注册的容器规则，所以基础规则缺失会导致变体失效
HTML 容器元素必须显式带 @container 类
CSS 里的 @container 规则不会自动“发现”某个元素是容器——它只定义查询条件。真正触发查询的，是 HTML 元素上那个 @container（或 @container/name）类。没有这个类，父容器尺寸再变，子元素也不会响应。
- 默认容器类型是
inline-size，即按宽度查询；如需按高度或块方向响应，得额外加container-type-block-size工具类（需插件支持） - Grid 容器要生效，除了
@container类，还得有container-type-inline-size（或等效 CSScontainer-type: inline-size） - 命名容器如
@container/sidebar，对应 HTML 必须写@container/sidebar，不能只写@container再靠 CSS 匹配——命名是双向绑定的
experimental.containerQueries 开关在根级、@tailwindcss/container-queries 插件已安装并 require、所有 @container 规则在 @layer 内。最容易被忽略的是最后一点——它不报错，只是彻底不生成 CSS，连 DevTools 都看不到痕迹。 
