CSSStyleSheet replaceSync 为什么忽略 @import 规则

我第一次把一段带有 @import 的 CSS 交给 CSSStyleSheet.replaceSync() 时，最容易误判的不是语法，而是资源模型：这个方法接收的是一组要同步放进构造样式表的规则，不是一个会继续加载外部文件的 CSS 入口。

结论很直接：replaceSync() 会保留可解析的普通规则，但会移除文本中的外部 @import 规则，并在控制台给出警告。需要查看官方定义时，可直接打开：

官方地址：https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleSheet/replaceSync

要让构造样式表稳定工作，把需要共享的 CSS 在进入 replaceSync() 前合并成可直接解析的规则；如果资源必须独立加载，就不要把它伪装成构造样式表里的 @import。

replaceSync 接受的是构造样式表内容

replaceSync() 和异步的 replace() 只能作用在 new CSSStyleSheet() 创建的构造样式表上。它们不是对页面中已有 的快捷改写，也不会把任意 CSS 文件地址当成加载任务。

// 创建可被 adoptedStyleSheets 共享的构造样式表
const sheet = new CSSStyleSheet();

// 传入已经准备好的普通 CSS 规则
sheet.replaceSync(`
  :host { display: block; }
  .title { color: #334155; }
`);

// 把同一个样式表交给 Shadow DOM 使用
const root = document.querySelector('#card').attachShadow({ mode: 'open' });
root.adoptedStyleSheets = [sheet];

这里的关键不是“同步”两个字，而是样式表的来源和内容边界。构造样式表有自己的规则集合，replaceSync() 负责一次性替换这组规则，成功时返回 undefined。

为什么 @import 会被移除

@import 代表外部样式资源关系，而 replaceSync() 的输入是要立即解析的 CSS 规则集合。把外部导入留在规则集合里，就会把同步替换和后续资源加载混在一起，资源顺序、错误处理和同步语义都会变得不清晰。因此规范边界是：外部导入被删除，同时打印警告。

// 这个示例只用于说明资源边界，不把 @import 当作可用的外部加载器
const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  /* 普通规则可以进入构造样式表 */
  .panel { padding: 12px; }
  /* 外部 @import 会被移除并触发控制台警告 */
  @import url("theme.css");
`);

// 需要外部文件时，应在构造样式表之外管理它的加载与生命周期
console.log(sheet.cssRules.length);

所以看到“样式没生效”时，先不要把它归因于选择器优先级。先检查传入字符串里是否包含外部 @import，再决定是把 CSS 合并进构造样式表，还是恢复为独立的样式资源。

预先合并 CSS 还是保留独立资源

我的取舍通常分成两类。组件内部需要和多个 Shadow DOM 一起复用的规则，适合在构建阶段合并后交给 CSSStyleSheet；页面级主题、可独立缓存的资源或需要单独替换的文件，则保留为普通 stylesheet，不把它们塞进 replaceSync()。

如果确实要使用异步方式，可以把已经合并好的 CSS 文本交给 replace()。它返回一个 Promise，适合等待文本准备完成的场景；“异步”并不等于“允许 @import”。

// 先得到已经合并好的 CSS 文本，再异步替换规则集合
async function installTheme(sheet, cssText) {
  try {
    // replace 返回 Promise，错误可以在调用方统一处理
    await sheet.replace(cssText);
    return sheet;
  } catch (error) {
    // 保留原错误，避免把资源加载问题伪装成样式优先级问题
    throw new Error(`主题规则替换失败: ${error.message}`);
  }
}

我会保留的三个判断点

第一，确认对象确实来自 new CSSStyleSheet()；否则调用替换方法会遇到 NotAllowedError。第二，把 @import 看成资源组织信号，而不是普通选择器：需要它独立存在，就放到构造样式表之外。第三，构造样式表的优势在共享和规则边界，不在替代所有 CSS 文件。

兼容性方面，MDN 将构造函数、replaceSync() 和 replace() 标为广泛可用，但具体项目仍应结合目标浏览器决定是否准备普通 stylesheet 降级。这样排查时，问题会从“为什么规则神秘消失”变成一个清楚的资源选择：要么合并后同步替换，要么保持外部资源独立。

相关问题

replaceSync() 和 replace() 有什么区别？ 前者同步替换并返回 undefined，后者异步替换并返回 Promise；两者都不能保留外部 @import。

可以把普通 标签的样式表传给 replaceSync() 吗？ 不可以。替换方法要求样式表由 CSSStyleSheet() 构造函数创建。

@import 被移除后应该怎么改？ 组件共享场景在构建阶段合并 CSS；需要独立缓存、主题切换或独立生命周期时，保留普通 stylesheet。