企业官网建设流程全解析

• 前端
• 构建工具

导读

本文以 css-blocks 项目根目录 CHANGELOG.md 为骨架，梳理该项目从 0.17.0 到 1.5.0 的完整演进脉络，并结合仓库源码（core、cli、config、eyeglass、ember、bem-to-blocks 等包）逐一印证每个里程碑背后的实现细节。读完本文，你将掌握 css-blocks 的核心架构（Block 解析、配置解析、同步/异步双工厂）、CLI 的 validate/convert 命令用法、Eyeglass 同步预处理接入方式、Ember/Glimmer 集成方案以及错误报告机制（MultipleCssBlockErrors、sourcemap 映射）等关键实战能力，并能直接依据源码路径深入探索。

css-blocks 是一个由 LinkedIn 维护的、基于 PostCSS 的样式系统 monorepo（当前仓库版本 1.5.0，见 lerna.json），其核心目标是"High performance, maintainable stylesheets"：以*.block.css文件描述可复用样式块，通过模板分析器（Analyzer）与重写器（Rewriter）在编译期把模板中的样式引用替换为最优化的 CSS 类名，从而获得高性能、可维护的样式输出。

1. 仓库形态与版本管理基线

在深入各版本之前，先明确仓库的工程组织方式，这有助于理解 CHANGELOG 中大量条目所指向的"包"。

• Monorepo 工具：使用 Lerna + Yarn Workspaces，见根目录 package.json 与 lerna.json。packages/@css-blocks/*下的所有包构成一个统一发布单元，版本号保持一致（当前为 1.5.0）。
• 发布规范：CHANGELOG 顶部声明遵循 Conventional Commits 中的约束），因此每次发布都会自动生成结构化的变更记录。
• 包清单（从目录结构可见）：core（核心 Block 解析/编译/分析）、cli（命令行工具）、config（配置加载）、broccoli（Broccoli 插件）、eyeglass（Sass/Eyeglass 预处理适配）、ember / ember-app / ember-cli / ember-utils / glimmer（Ember 与 Glimmer 集成）、jsx（JSX/Babel 集成）、webpack（webpack 插件）、bem-to-blocks（BEM 语法转换）、runtime（运行时样式计算）、language-server / vscode（语言服务器与编辑器集成）、test-utils 等。
• 版本节奏：从 2017 年底的 0.17.0 到 2020 年 9 月的 1.5.0，历经 0.x 功能迭代、1.0.0-alpha 系列、1.0.0 正式版，再到 1.5.0 的增量演进。

2. 0.17 – 0.19：核心抽象成型（BlockTree、冲突检测、优化分析）

这一阶段的变更集中在@css-blocks/core，为后续所有功能打下基础。

2.1 BlockTree 抽象与类型安全

0.18.0 的 Features 中密集出现 BlockTree 相关条目：Added BlockPath parser、Broke up Block.ts, refactored foundational BlockObject constructs, added StateGroup concept、Full type safety for all BlockTree objects、Remove BlockTree abstraction、Generisize StateGroup and State to Attribute and AttrValue。

从当前源码看，这些抽象最终沉淀为 BlockTree 目录 下的Block、BlockClass、Attribute、AttrValue、Style、Styles、RulesetContainer、Inheritable等类。其中StateGroup/State被泛化为Attribute/AttrValue，意味着样式块的状态（state）被统一建模为属性-值对，这直接支撑了后续"属性组（attribute groups）"的运行时数据输出（1.3.0 特性）。BlockPath 解析器则位于 BlockSyntax/BlockPath.ts，负责解析block.class这类路径语法。

从源码结构可以推断：这一系列重构的目标是让 Block 树上的每个节点都具备编译期可校验的类型，为冲突检测（见 2.2）提供可靠基础。

2.2 冲突解决（Conflict Resolution）与媒体查询

0.18.0 引入Conflict Resolution Validator，其实现对应 BlockCompiler/ConflictResolver.ts 与 BlockCompiler/conflictDetection.ts。1.0.0-alpha.4 又修复了"Conflict Resolutions with Media Queries"（#372），即冲突检测必须考虑媒体查询作用域。

验证这些逻辑的测试在 validations/property-conflict-validator-test.ts。冲突解决器负责在多个样式同时命中同一元素时，判定哪些属性声明相互冲突、哪些可以安全合并，这正是"可维护样式"的核心保障——它保证样式冲突在编译期被显式解决，而不是留到运行时由 CSS 层叠规则裁决。

2.3 优化分析（opticss）的接入

0.18.0 的Support opticss enabled analysis of css-blocks意味着核心开始接入 opticss 优化引擎。当前源码中，Analyzer 的优化相关配置通过 Analyzer/Analyzer.ts 的optimizationOptions传递，CLI 的 convert-test.ts 与 opticss-test.ts 分别覆盖了 CLI 与 core 层的优化流程。生产构建默认开启优化是在 1.0.0-alpha.4（见下文第 5 节）。

3. 0.20 – 0.24：CLI、preprocessor、Ember 生态与错误体验提升

3.1 CLI 的诞生与演进

0.22.0 创建了@css-blocks/cli（"Initial implementation"、"Add preprocessor support to the cli"），0.23.0 声明了 bin 脚本，0.23.1 修复了缺失的 bin。当前 cli/src/index.ts 展示了完整命令体系：

css-blocks <cmd> [options] block-dir-or-file...

• validate <blocks..>：校验 block 文件语法。传目录时会递归发现目录下的**/*.block.*文件（1.4.0 特性"如果传给 validate CLI 的是目录，则发现 blocks"在此实现，见 cli/src/index.ts 中fse.statSync(blockFile).isDirectory()分支）。校验通过输出绿色ok，失败则输出红色错误并统计错误数。
• convert <files..>：调用@css-blocks/bem-to-blocks把 BEM 语法转换为 block 文件语法（详见第 7 节）。
• 全局选项：--preprocessors <js-file>（导出按扩展名映射的预处理函数）、--npm（允许从 node_modules 导入）、--alias <alias> <dir>（定义导入别名，隐含--npm）。

CLI 的validate会先在待校验文件所在目录向上搜索 css-blocks 配置文件（searchForConfiguration，来自@css-blocks/config），再把--preprocessors/--npm/--alias选项合并进配置，最后用BlockFactory逐个加载并解析 block 文件。

3.2 错误报告体验：sourcemap 与源码上下文

0.24.0 带来一批错误体验改进：

• Display selector error locations using sourcemaps
• Use sourcemaps for errors involving non-selector nodes
• Track ranges instead of only the start position for errors
• cli: Display error in context with the source file's contents

这些在 cli/src/index.ts 的handleCssBlockError/displayError/displaySnippet中得到完整实现：CLI 能区分CascadingError（显示caused前缀并递归到根因）与MultipleCssBlockErrors（逐条列出所有子错误）；当错误位置带generated映射时，会先显示编译产物中的位置，再显示 sourcemap 映射回源码的位置，并高亮出错的代码行与具体列区间（splitLineOnErrorRange）。核心层的错误类型定义见 core/src/errors.ts，其中charInFile、errorHasRange、hasMappedPosition正是 CLI 判断"能否展示源码片段"的依据。

3.3 包导入能力：npm 与别名

0.23.0 的 "Imports via npm and aliases" 对应 core/src/importing/NodeJsImporter.ts：它允许@block指令从 node_modules 解析，也支持配置别名。CLI 的--npm/--alias选项即用于创建该 importer（cli/src/index.ts 中new NodeJsImporter(aliases)）。1.0.0-alpha.0 进一步引入"per block namespaces"与block-alias语法，使@block myBlock from "./my-block.block.css"这种按块命名空间的引用方式成为主流写法。

3.4 Ember 集成与缓存失效

0.20.0 系列完成了 Ember CLI 集成：

• 0.20.0-beta.8："Use separate file for CSS staging, merge app.css at end" —— 先把编译产物暂存到独立文件，最后再与 app.css 合并，避免编译过程污染应用样式。
• 0.20.0-beta.3：Ember CLI addon Preprocessor 支持。
• 0.23.2：通过ember-source的存在来检测 Ember 环境（Detect ember by presence of ember-source）。
• 0.24.0：Invalidate handlebar template caches when dependent blocks change—— 模板缓存必须随依赖 block 文件变化而失效。

当前 ember/src/index.ts 展示了 addon 的完整接线：setupPreprocessorRegistry注册htmlbars-ast-plugin，optionsForCacheInvalidation把aliases、analysisOpts、optimization、parserOpts组装成缓存键，保证配置变化时 HTMLBars 插件缓存正确失效；preprocessTree("css")阶段则把所有*.block.css及编译产物从 CSS 树中剔除（withoutCssBlockFiles），因为 block 文件已在模板树中被编译处理。

4. 1.0.0-alpha 系列：为正式版铺路的关键重构

4.1 配置体系的最终定型（Options → Configuration 重命名）

1.0.0-alpha.0 引入"Configuration file API"与"Basic preprocessor support"，而 0.18.0 曾完成一轮大改名：

• normalizeOptions→resolveConfiguration（模块名改为resolver）
• SparseOptions→Options
• ReadonlyOptions→ResolvedConfiguration
• Options→Configuration
• data选项 →importerData

当前源码 core/src/configuration/types.ts 定义了Configuration（完整配置）、Options（用户可传入的Partial<Readonly<Configuration>>）、ResolvedConfiguration（已填充默认值的只读配置）；core/src/configuration/resolver.ts 的resolveConfiguration()负责把用户选项与默认值合并，默认值如下：

其中guidAutogenCharacters的语义（见 types.ts 注释）是：GUID 基于文件唯一标识符（通常是绝对路径）的哈希生成，默认 5 个字符；仅在极罕见的 GUID 冲突时才有必要调大。1.2.0 的 "Use incoming GUIDs. Ensure uniqueness." 与 "Only register guids from blocks that are valid"（1.4.0）正是围绕 GUID 注册与冲突检测的后续打磨，其实现可见 BlockFactorySync.ts 中的registerGuid调用——只有block.isValid()的块才注册 GUID，出错块会重新解析。

4.2 配置文件的同步加载与 CLI 接入

1.1.0 与 1.2.0 两次提交 "Make configuration loading synchronous with async wrapper"（#365：

• searchSync(searchDirectory)：从指定目录向上逐级查找css-blocks.config.json、css-blocks.config.js或package.json（取其"css-blocks"键），支持extends递归继承、rootDir/preprocessors/importer的路径解析与 JS 文件加载。
• search()：searchSync的异步包装，用于向后兼容。
• load(configPath)：从已知路径显式加载配置文件。

CLI（cli/src/index.ts）在validate中使用searchForConfiguration(searchDir)读取配置；1.1.0 还修复了"css-blocks 配置文件应优先于 package.json"（A css-blocks config file should take precedence over package.json），这由 cosmiconfig 的searchPlaces顺序（css-blocks.config.json→css-blocks.config.js→package.json）保证。

4.3 语言服务器与 VS Code 集成

1.0.0-alpha.0 集中引入了 language-server 能力：Basic workings of language server and vscode client、Code completion and definitions for per-block namespace syntax、Add document links provider、Adding a custom importer for the language-server、Adds custom css data for css-blocks at rules；1.0.0-alpha.1 又补上 "Adds find references capability"。

这些能力分布在 language-server/src：completionProviders/emberCompletionProvider.ts、definitionProviders/emberDefinitionProvider.ts、documentLinksProviders/blockLinkProvider.ts分别对应补全、定义跳转与文档链接；Importer.ts是语言服务器专用的自定义 importer（需要容错地解析不完整文件）；VS Code 侧的自定义 CSS 数据（@block等 at-rule 的语法提示）见 vscode/css-blocks.css-data.json。

4.4 错误机制升级：MultipleCssBlockErrors

1.0.0-alpha.5 引入新错误类体系：Adding a new class of errors - MultipleCssBlockErrors、Pass multiple errors to the language server，并把 composes/export/import 等校验逐步迁移到多错误模型。其实现位于 core/src/errors.ts：

• MultipleCssBlockErrors是CssBlockError的子类，内部持有CssBlockError[]，构造时自动"扁平化"嵌套的 MultipleCssBlockErrors（处理传递性错误）。
• CascadingError携带cause（根因），错误详情格式化（errorDetails）会递归展开"多错误 + 级联错误"树。
• 1.4.0 的 "Correctly count the errors in block files" 保证错误计数准确（CLI 中errorCount的累加逻辑见 cli/src/index.ts）。

这一机制是编译期错误报告体验的关键：一个 block 文件可能同时存在多个语法/校验问题，多错误模型让用户一次看到全部问题，而不是修一个报一个。

5. 1.0.0 正式版：Node 版本策略与可选 Preprocessor

1.0.0（2020-04-04）是首个正式版本，包含三项值得关注的变更：

5.1 破坏性变更：Node 支持范围收窄

### BREAKING CHANGES * Node 8 is now out of maintenance so we have dropped support for node 6 and 8. Node 11 is no longer needed because node 12 was released.

即 1.0.0 起仅支持 Node 10 与 12（在当时 LTS 语境下的合理收窄）。这与仓库根 package.json 的 volta 配置（node: 12.2.0）一致。注意：这是 2020 年的版本策略，当前环境是否可用应以读者实际使用的 Node 版本为准——旧版本 css-blocks 可能需要兼容性处理。

5.2 可选 Preprocessors 与库/应用 API 契约

"Optional Preprocessors & library/application API contract" 意味着预处理器变为可选：如果某个语法没有声明 preprocessor，且该文件就是css语法，则直接透传内容（见 BlockFactorySync.ts 中preprocessor()方法的最后一个分支：css 文件返回恒等 preprocessor）；若是非 css 语法且未提供 preprocessor，则抛错No preprocessor provided for ${syntaxName(syntax)}。

5.3 style-of 与 eyeglass 包

• style-of：1.0.0 的style-of: Allows positional arguments to be passed与Errors if unsupported params have been passed涉及 Glimmer/Ember 模板中的style-ofhelper（1.0.0-alpha.5 为 glimmer 增加style-ofhelper，#383 与 glimmer/test。
• eyeglass：新增@css-blocks/eyeglass包，"Adds new package that enables simple Eyeglass support"。该包详见第 6 节。

5.4 生产构建默认开启优化

1.0.0-alpha.4 的 "Enable optimization for production builds by default" 意味着：生产模式下，样式会被 opticss 优化器深度精简（去除不可达样式、合并规则集）。相关配置读取逻辑可参考 ember-utils/src/options.ts 中isProduction相关的默认值处理。

6. 1.1 – 1.5：同步化革命与 Ember v2 管线

这一阶段的主线是"同步化"：同步 Block Factory、同步预处理、同步配置加载，最终让 Ember v2 构建管线端到端受益。

6.1 Synchronous Block Factory（1.5.0）

1.5.0 的 "Synchronous Block Factory" 引入BlockFactorySync，实现在 core/src/BlockParser/BlockFactorySync.ts。其要点：

• 与异步BlockFactory（BlockFactory.ts）共享BlockFactoryBase（BlockFactoryBase.ts），文件头部注释明确提醒"两个文件存在大量重复，改动需保持同步"。
• isSync: true标记同步身份；getBlockFromPath要求绝对路径，先经 importer 转为FileIdentifier再走getBlock。
• 内部维护blocks与paths两个缓存字典，保证同一 block 只解析一次（"Multiple instances of the same block will result in analysis and optimization bugs"）。
• 处理ImportedCompiledCssFile（预编译 CSS 文件导入）时，会读取定义文件（definition AST）构造 Block，再把 CSS 规则合并进 Block（_mergeCssRulesIntoDefinitionBlock），并校验block-syntax-version（1.2.0 的 "Validate block-syntax-version"，相关常量见 PrecompiledDefinitions/block-syntax-version.ts）。
• 1.5.0 的 "Update the debug identifier for BlockFactorySync" 与 "Remove some lingering traces of the async factory" 属于对同步工厂的收尾清理。

同步工厂的价值：让 CLI、eyeglass、webpack loader 等无法（或不适合）使用异步 Promise 管线的场景也能直接使用 css-blocks 的完整解析能力。

6.2 同步预处理与 Eyeglass 集成

1.5.0 的 "Update eyeglass integration to support synchronous preprocessing" 与 eyeglass/src/index.ts 一一对应：

• adaptor(sass, eyeglass, options)：返回异步 preprocessor，内部用sass.render+ eyeglass 编译，产出content、sourceMap、dependencies（res.stats.includedFiles）。
• adaptorSync(...)：使用sass.renderSync的同步版本。
• DirectoryScopedPreprocessor：限定只处理指定目录（含子目录）内文件的 preprocessor provider，init()中通过setEyeglassRoot把 eyeglass root 设为该目录。1.5.0 的修复 "Set eyeglass root within a directory-scoped processor" 与 "Pass a copy of sass options for sync setup" 都落在这里：init()用cloneDeep(options)复制选项，避免同步/异步两份配置互相污染；同时提供setupOptionsSync?钩子供子类调整同步编译选项。
• adaptAll / adaptAllSync：把多个 adaptor / provider 组合成一个统一的 preprocessor，逐个尝试，最后用兜底 adaptor。

配置侧的同步接入是preprocessorsSync配置项（见 4.1 表格），BlockFactorySync的构造函数直接读取this.configuration.preprocessorsSync（BlockFactorySync.ts）。

6.3 预处理链（preprocess chaining）

配置项disablePreprocessChaining控制的是这样一个行为（见 BlockFactorySync.ts 的preprocessor()方法）：若某文件是 scss 等非 css 语法，且同时声明了css语法的 preprocessor，则默认会在该语法 preprocessor 之后再跑一遍 css preprocessor（并把 sourcemap、dependencies 合并）。设置disablePreprocessChaining: true可关闭此行为。

6.4 Ember v2 管线：ember-app、运行时数据与 sourcemap

1.2.0 与 1.3.0 围绕"Ember v2"（Glimmer/Octane 时代）做了大量工作，创建了@css-blocks/ember-app包：

• 运行时数据生成：ember-app/src/RuntimeDataGenerator.ts 生成运行时可用的样式计算数据（"Basic runtime data generation"、"Optimized css in ember-app build output"、"Enable optimizer and runtime rewriting of optimized styles"）。
• 聚合重写数据：ember-app/src/AggregateRewriteData.ts 定义聚合重写的数据 schema（1.2.0 "Data schema for Aggregate Rewriting"）；1.3.0 的 "Emit attribute groups in the runtime aggregate rewrite data" 让运行时数据携带属性组信息。
• Sourcemap：1.4.0 的 "End-to-end sourcemaps for ember v2 pipeline" 打通了从模板源 → 编译产物 → 源码的完整 sourcemap 链路。
• runtime 包：runtime/src/runtime.ts 是运行时的样式求值逻辑（1.3.0 "Extract StyleEvaluator, StyleResolver classes from runtime service" 将其从服务中抽离为独立类），相关测试见 runtime/test/expression-test.ts。

1.2.0 还修复了多个 Ember 集成细节：Namespace blocks within each app/addon/engine（每个 app/addon/engine 内对 block 命名空间隔离）、Cache invalidation when block files change、Ensure compiled css is not in vendor.css/Exclude compiled blocks from vendor.css（1.4.0，编译产物不应混入 vendor.css）、Only merge with app.css if it exists、Sometimes there's no css blocks output（1.3.0）等。

6.5 1.5.0 的其他修复

• "Pick up fix for opticss crash on unknown css declarations"：随 opticss 升级修复未知 CSS 声明导致的崩溃。
• "Prune css-blocks.css from the output after concatenating it"：拼接后清理css-blocks.css残留（CLI 侧 concat 相关逻辑见 cli/test/convert-test.ts）。
• "Add file+loc to class name conflict error" 与 "Class name collision detection"：类名冲突检测，冲突时报错信息包含文件与位置。
• "Scan app CSS for classes"：扫描应用 CSS 中的类名，用于冲突检测。

7. bem-to-blocks：BEM 到 CSS Blocks 的转换器

1.0.0-alpha.5 创建了@css-blocks/bem-to-blocks包（"Creating a new package for bem to css-blocks conversion"），CLI 的convert命令即调用它。其实现 bem-to-blocks/src/index.ts：

• 两遍处理：第一遍遍历所有选择器，把 BEM 类名解析为BemSelector（block/element/modifier 三段），无法自动解析的类名通过 userInput.ts 交互式询问用户（inquirer.js，见 1.0.0-alpha.5 的 "Making the CLI interactive using inquirer.js"）；第二遍把每个 BEM 选择器重写为 block 语法。
• 重写规则（rewriteSelectors）：
  • element → 类名（如.block__element→.element）；
  • modifier → 状态属性（如.block--is-active→ 属性[is-active]或带 subState 的[state="subState"]）；
  • 直接挂在 block 上的修饰符 → 在:scope上表达状态。
• 子状态优化（constructBlocksMap）：对同一元素上多个 modifier 求最长公共子串（LCS，见 utils.ts 的findLcsMap），把公共前缀提升为 state、剩余部分作为 subState；同时去除is-前缀（对应 1.0.0-alpha.5 的 "Removing common prefixes from states, like, is"）。
• 异步化：1.0.0-alpha.5 的 "Making bem-to-blocks asynchronous" 反映在processBEMContents返回 Promise 上；"Address race condition by simplifying main loop for BEM conversion" 则简化了主循环以规避竞态。

CLI 用法示例（从 cli/src/index.ts 与测试 cli/test/convert-test.ts 可见）：

# 校验目录下所有 block 文件（目录会被递归发现） css-blocks validate ./app/styles # 将 BEM 样式文件转换为 *.block.css css-blocks convert ./styles/button.css

转换产物写为*.block.css（文件名约定，见 bem-to-blocks/src/index.ts 中ext: \.block${parsedFilePath.ext}`` 的逻辑）。

8. 1.4.0：类名冲突检测与编译产物处理

1.4.0 的三项特性值得单独说明：

• 类名冲突检测（Class name collision detection）：配合 "Scan app CSS for classes" 与 "Add file+loc to class name conflict error"，css-blocks 会扫描应用已有 CSS 中的类名，若生成的类名与之冲突，报错信息会带上具体文件与位置。这解决了"生成的类名与手写 CSS 类名撞车"这一真实场景问题。
• validate目录发现：CLI 传目录时自动发现*.block.*文件（已在 3.1 详述）。
• 拼接设置可覆盖（Provide ability to override concat settings）：Ember 管线中 CSS 拼接（concat）行为可通过配置覆盖，相关文档修复 "Typo in concat options docs" 同步跟进。concat helper 的缺失在 1.3.1 中修复（"Add missing concat helper"）。

9. 从 CHANGELOG 读出的工程实践与演进规律

回顾完整版本史，可以提炼出 css-blocks 的几条工程演进规律：

1. 先抽象后集成：0.18 时代先打磨 BlockTree 抽象与冲突检测，1.0 时代再把这些能力开放为配置 API 与 CLI，最后（1.1–1.5）才大规模接入 Ember v2 与同步管线。
2. 配置体系持续收敛：从Options家族的反复重命名（SparseOptions → Options → Configuration → ResolvedConfiguration）可以看出，团队在 1.0 之前刻意把"用户可传入的选项"与"已解析的只读配置"严格区分，并统一收敛到resolveConfiguration()单一入口。
3. 错误报告是核心竞争力：从 sourcemap 定位、行区间追踪、源码上下文展示，到 MultipleCssBlockErrors 的多错误聚合，整个错误体系在 0.24–1.0 期间被反复打磨，说明编译期 DX（开发者体验）被当作一等公民对待。
4. 同步化是生态适配的关键：Eyeglass、webpack loader、CLI 这些工具链往往运行在同步语境下，BlockFactorySync+preprocessorsSync+searchSync的"三同步"组合，让 css-blocks 能被更多构建工具直接消费。

10. 延伸阅读：深入仓库的入口

若想进一步验证或研究本文所述内容，建议从以下路径入手：

• CHANGELOG.md：本文的骨架来源，每个版本条目都带 commit 链接。
• core/src/configuration：配置类型与resolveConfiguration。
• core/src/BlockParser：BlockFactory、BlockFactorySync、BlockFactoryBase、BlockParser与预处理逻辑（preprocessing.ts）。
• core/src/BlockCompiler：冲突解决器与冲突检测。
• core/src/errors.ts：错误类型体系（含MultipleCssBlockErrors、CascadingError）。
• cli/src/index.ts：CLI 命令与错误展示实现。
• config/src/index.ts：配置文件搜索与加载。
• eyeglass/src/index.ts：Sass/Eyeglass 同步/异步预处理适配。
• ember/src/index.ts 与 ember-app/src：Ember v2 集成与运行时数据生成。
• bem-to-blocks/src/index.ts：BEM 转换器实现。
• 各包test/目录：如 core/test/opticss-test.ts、cli/test/convert-test.ts、runtime/test/expression-test.ts，覆盖了本文引用的绝大多数行为。

• 前端
• 构建工具