Ember 应用集成 CSS Blocks 完整指南:@css-blocks/ember-app 插件的安装、配置与测试实践

原创2026-10-06 13:42:201,894 阅读
文章标签:前端构建工具

Ember 应用集成 CSS Blocks 完整指南:@css-blocks/ember-app 插件的安装、配置与测试实践

@css-blocks/ember-app 是 CSS Blocks 在 Ember 生态中的"应用侧" ember-cli addon,负责把应用(及 addon、engine)中通过 CSS Blocks 撰写的样式编译、拼接、优化,并生成模板运行所需的运行时数据。读完本文,你将掌握如何接入该 addon、理解全部配置选项的语义与底层实现、以及如何在类名被随机化后依然写出健壮的测试。

addon 的定位:应用侧构建管线的收口

CSS Blocks 在 Ember 中的构建被拆成两个 addon,各自职责清晰:

  • @css-blocks/ember:面向"撰写 CSS Blocks 的一方",负责在模板编译期分析模板与样式、将中间产物(compiled CSS 与 Definition 文件)输出到编译树中,适用于应用、addon 与 engine;
  • @css-blocks/ember-app(本文主角):面向"最终消费 CSS 的一方",即 Ember 应用本身。它把所有 CSS Blocks 内容汇集起来、拼成最终产物、交给 OptiCSS 优化,并生成一份 JSON 运行时数据(runtime data)与对应的 helper,供重写后的模板在运行时解析出应该给元素加上哪些类名。

任何"撰写"了 CSS Blocks 文件的 addon 或 engine,其所在的应用都必须把 @css-blocks/ember-app 作为依赖,否则不会产出任何 CSS 输出。这也是 package.json 中 ember-addon.after 声明为 <a href="https://link.gitcode.com/i/3b8f9de1db5074716095ea2cd743ecfe" target="_blank">"@css-blocks/ember"] 的原因——它必须在 @css-blocks/ember 完成模板侧编译之后再执行。参见 [packages/@css-blocks/ember-app/package.json。

一个容易忽略的细节是:CSS Blocks 的编译实际发生在模板树而非样式树中。正如 addon 入口 顶部注释所说,CSS Blocks 需要同时理解模板与样式才能完成模板重写,因此 JS/模板树的处理先于 CSS 树,preprocessTree 中特意对 "CSS 树先于 JS 树运行" 的情况抛出明确错误("[css-blocks/ember-app] The CSS tree ran before the JS tree...")。

快速开始:三步接入

按照 官方 README 的 Basic Usage,接入只需要三步:

  1. 在应用中将 @css-blocks/ember-app 添加为依赖;
  2. 如果应用自身也在用 CSS Blocks 撰写样式,同时把 @css-blocks/ember 添加为依赖;
  3. 运行 ember build。

构建产物落位规则:

  • 若应用存在 app/styles/app.css,CSS Blocks 的编译输出会被自动追加到该文件末尾(由 postprocess 阶段的 broccoli-concat 完成);
  • 若应用因预处理等原因使用了其他样式文件名,则构建期间会在应用样式目录生成一个名为 app/styles/css-blocks.css 的文件,供你的预处理器 import,或与其他文件拼接成最终的 CSS。

另外,如果应用使用 engine,每个用到 @css-blocks/ember 的 engine 都必须把 css-blocks service 作为依赖加入(该 service 位于 runtime/app/services,由 addon 的 treePaths.app 注入,见 runtime 目录)。

开发构建与生产构建的输出差异是刻意设计的:

  • 开发构建:产出带开发者友好 BEM 类名的 CSS,方便你理解应用结构;
  • 生产构建:产出经过拼接(concatenated)、优化(optimized)、压缩(minified)的 CSS 工件。

从源码看,这一差异由 ember-utils 的 getConfig 落实:optimization.enabled 在未显式设置时默认取 isProduction,即生产构建才默认开启优化;同时 parserOpts.outputMode 被强制设置为 OutputMode.BEM_UNIQUE,保证类名唯一性。

配置选项(Options)详解

所有选项都通过应用 ember-cli-build.js 中的 css-blocks 属性传入。下表汇总了 README 与 ember-utils 的接口定义 中的全部参数:

选项 类型 默认值 作用
output string "css-blocks.css" 修改 CSS Blocks 样式写入 app/styles 目录时的文件名;一旦设置,不再自动与 app/styles/app.css 拼接
aliases object {} 导入别名映射,值为指向包含 CSS Block 文件目录的绝对路径
analysisOpts object {} 模板分析选项,一般无需设置
parserOpts object 自动加载 传给 CSS Blocks 解析器与编译器的选项;未设置时自动从 css-blocks.config.js 读取
optimization object { enabled: isProduction } 传给 OptiCSS 优化器的选项,可选择性开关具体优化,或将 enable 设为 false 整体禁用
broccoliConcat object | false {} 控制 broccoli-concat 行为;设为 false 则不执行拼接,需自行把编译内容并入最终 CSS
appClasses string[] [] 应用 CSS 中使用、可能与优化器冲突的类名清单;短类名(约 5 字符)应加入此列表

output:定制输出文件名

output 决定编译 CSS 的落盘文件名。底层实现见 filepaths.ts:预处理阶段路径为 app/styles/${output}(默认 app/styles/css-blocks.css),postprocess 阶段则出现在 assets/${output}。注意设置该选项后,自动拼接行为会被跳过,你需要自行在样式管线中包含该文件。

aliases:目录级导入别名

aliases 的键作为导入别名,值必须是绝对路径。例如:

// ember-cli-build.js
const path = require('path');

module.exports = function(defaults) {
  let app = new EmberApp(defaults, {
    'css-blocks': {
      aliases: {
        myblocks: path.resolve(__dirname, '../blocks')
      }
    }
  });
  return app.toTree();
};

配置后,@block foo from 'myblocks/header.block.css'; 即可导入 ../blocks 目录下的 header.block.css。在 ember-utils 的 getConfig 中,aliases 会被注入到默认的 NodeJsImporter:options.parserOpts.importer = options.parserOpts.importer || new NodeJsImporter(options.aliases)——即只有在没有自定义 importer 时才使用别名 importer。

parserOpts 与 css-blocks.config.js

parserOpts 是传给 CSS Blocks 解析器/编译器的选项。若未显式提供,构建时会通过 config.searchSync(root) 自动从 css-blocks.config.js 加载(同样由 ember-utils getConfig 完成)。使用配置文件的好处是:其他工具(如 @css-blocks/cli 命令行)可以加载与 Ember 应用完全一致的选项。

getConfig 还会做几件关键的兜底与校验(options.ts):

  • parserOpts.rootDir 缺省时设为应用根目录(root),这是解析相对导入所必需的;
  • output 若非字符串会抛出明确错误:Invalid css-blocks options in 'ember-cli-build.js': Output must be a string.;
  • optimization.enabled 未设置时取 isProduction。

optimization:OptiCSS 优化器配置

optimization 直接透传给 OptiCSS 的 Optimizer。在 broccoli-plugin.ts 的 CSSBlocksApplicationPlugin.build() 中,优化器会逐一装载应用及其传递依赖的 blocks 分析结果(optimizer.addAnalysis(...))与编译后的样式源(optimizer.addSource(...)),最终调用 optimizer.optimize(cssFileName) 产出优化 CSS,并额外写出 .optimization.log 优化日志与 app/styles/css-blocks-stylelist.json 类名清单。

broccoliConcat:拼接行为控制

postprocess 阶段由 addon 入口 postprocessTree 使用 broccoli-concat 将 assets/css-blocks.css 与 assets/<modulePrefix>.css(即应用自身样式)拼接为最终文件,同时开启 sourcemap(mapCommentType: "block"、extensions: <a href="https://link.gitcode.com/i/b51215383586dcb84dd902ed6dbf0a52" target="_blank">"css"])。如果 broccoliConcat 设为 false,postprocess 会直接跳过拼接,你必须增加额外处理把 CSS Blocks 编译内容并入最终 CSS 工件。默认拼接顺序在 [buildDefaultBroccoliConcatOptions 中可见:inputFiles: [blocksCssPath, appCssPath],即 CSS Blocks 内容在前、应用样式在后。

appClasses:与应用类名冲突的规避

优化器会重写类名,若应用 CSS 中存在短类名(约 5 字符),可能与优化器生成的类名撞车。appClasses 是 optimization.rewriteIdents.omitIdents.class<a href="https://link.gitcode.com/i/de22f789d5eab32ec7e989b36df14075" target="_blank">] 的便捷别名,底层实现在 [broccoli-plugin.ts 的 reserveClassnames:它会解析 rewriteIdents(布尔或对象形态),把 appClasses 并入 omitIdents.class 列表,确保优化器生成类名时避开这些名字。它仅在优化开启时生效。

值得注意的是,即使配置了 appClasses,postprocess 阶段仍会执行一次冲突检测:CSSBlocksStylesPostprocessorPlugin 会扫描应用 CSS(排除 CSS Blocks 自身产物)中的所有 .class 选择器,与优化器生成的类名比对,若发现冲突会直接抛错并提示你将短类名加入 css-blocks.appClasses。检测日志(含出错 CSS 的解析异常)会写入 assets/app-classes.log 供排查。

构建管线源码级拆解

ember build 时 addon 经历两条树管线,均实现在 src/index.ts:

JS/模板树(preprocessTree, type === "js"):针对应用(env.isApp)创建 CSSBlocksApplicationPlugin 实例,输入为应用 addon 树、JS 树以及(若有 lazy engine)收集到的 lazy-tree-output。该插件在 broccoli-plugin.ts 中承担核心工作:

  1. 扫描输入树中所有 *.block-analysis.json 与 *.compiledblock.css 产物(由 @css-blocks/ember 在模板编译期生成);
  2. 用 EmberAnalyzer 反序列化分析结果,收集全部使用的 blocks;
  3. 对每个 block 编译/复用 CSS,交给 OptiCSS Optimizer 做全局优化;
  4. 写出优化后的 CSS(含 base64 内嵌 sourcemap)、优化日志、类名清单;
  5. 用 RuntimeDataGenerator 生成运行时数据 -css-blocks-data.js,开发构建下还会额外生成 -css-blocks-test-support-data.js(见 RuntimeDataGenerator.ts 与 TestSupportDataGenerator.ts)。

CSS 树(preprocessTree, type === "css"):CSSBlocksStylesPreprocessorPlugin 把模板树中产出的 CSS Blocks 内容写入样式树的 app/styles/css-blocks.css(路径随 output 变化),并把 css-blocks-stylelist.json 转发给后续管线。

postprocess(type === "css"):若 broccoliConcat 未禁用,先运行冲突检测(优化开启时),再用 broccoli-concat 拼接产物,最后把原 css-blocks.css 从输出树中剔除(见 index.ts 的 mergedTree exclude 逻辑),避免重复出现在最终 CSS 中。

测试支持:setupCSSBlocksTest 的正确姿势

为什么需要它

接入该 addon 后,所有 CSS 类名与你在 block 文件中写下的完全不同——它们是优化器重新生成的结果,且跨构建、跨机器都可能变化;优化后元素上的类名数量也可能与源码中大相径庭。这是刻意设计:逼你不在测试中硬编码任何类名选择器,从而保证测试跨环境稳健。

测试服务的工作原理

addon 在开发构建下会生成 -css-blocks-test-support-data.js,其中 testSupportData 把"用户可读的 block 文件路径 + block 导出名"映射到该 block 的运行时 guid(见 TestSupportData.ts 中的注释示例)。setupCSSBlocksTest() 在 beforeEach 中把应用默认的 css-blocks service 替换为 CSSBlocksTestService(css-blocks-test-support.ts),后者通过 guid 反向解析出人类可读的代理类名(<guid><styleName>),于是你可以用 element.classList.contains() 断言样式是否存在。

注意:testSupportData 只暴露属于应用命名空间(应用、in-repo addon、in-repo engine)的 blocks,因为这些才代表需要测试的样式接口。运行时的类名解析链路(直接样式 → 隐含样式 → 优化后样式)实现在 css-blocks.ts、StyleEvaluator.ts 与 StyleResolver.ts,数据格式定义见 AggregateRewriteData.ts。

测试接入步骤

  1. 在集成或验收测试中调用 setupCSSBlocksTest(),且必须在 setupTest | setupRenderingTest | setupApplicationTest 之后调用(否则会抛出 "setupCSSBlocksTest must be called after setupTest|setupRenderingTest|setupApplicationTest")。它同时兼容 ember-qunit 与 ember-mocha;
  2. 该函数挂在应用命名空间的 service 上,需按如下方式导入:
    import { setupCSSBlocksTest } from '<appName>/services/css-blocks-test-support';
    
  3. 之后通过 this.cssBlocks 访问测试 service,其核心 API 是 this.cssBlocks.getBlock(<pathToBlock>, <blockName>):
    • pathToBlock 以所属应用名、in-repo addon 名或 engine 名开头;
    • blockName 可选,缺省返回该 block 文件的默认 block;
    • 返回的运行时 block 可用 .style(<styleName>) 查询样式名,再配合 element.classList.contains() 断言。

完整示例

import { setupCSSBlocksTest } from 'my-very-fine-app/services/css-blocks-test-support';

module('Acceptance | css blocks test', function (hooks) {
  setupApplicationTest(hooks);

  setupCSSBlocksTest(hooks);

  test('visiting /', async function (assert) {
    await visit('/');
    let defaultBlock = this.cssBlocks.getBlock("my-very-fine-app/styles/components/application", "default");
    let element = find('[data-test-large-hello]');
    assert.ok(element.classList.contains(defaultBlock.style(':scope[size="large]')));
  });
});

若传入的 block 文件或样式名不存在,测试 service 会给出包含可用选项的明确报错("No block file named ..." / "No style named ..."),便于快速定位。

常见陷阱(Common Gotchas)

截至本文,README 的 Gotchas 章节 内容为空("Nothing yet..."),但结合源码可以归纳出几个实践中容易踩坑的点:

  • 忘记添加 @css-blocks/ember:应用若自己撰写 CSS Blocks 却只装了本 addon,将不会生成任何 CSS 输出(addon 依赖模板树中的中间产物);
  • 忘记给 engine 加 css-blocks service 依赖:使用 engine 时必须逐引擎声明,否则该引擎的样式不会正常解析;
  • 应用 CSS 短类名冲突:若构建报出 "Your application CSS contains classes that are also generated by the CSS optimizer" 错误,按提示把相关短类名加入 css-blocks.appClasses 即可;
  • 自定义 output 后丢失自动拼接:设置 output 意味着你需要自行把生成的 CSS 文件纳入最终样式产物;
  • 禁用 broccoliConcat 后产物缺失:broccoliConcat: false 会跳过拼接,需要额外处理步骤补上 CSS Blocks 内容。

延伸阅读

登录后查看全文
css-blocks