Bulma 版本演进全景：从 CHANGELOG 看 0.x 到 1.0 的关键变更与升级要点

Bulma 的 CHANGELOG.md 完整记录了框架自 0.0.17 至 1.0.4 的全部版本变更，是升级 Bulma 时最重要的参考文件。本文以该文档为主体，梳理每个大版本的核心特性、破坏性变更与废弃警告，并结合当前仓库的构建脚本、Sass 源码（如主题、前缀、断点 mixin）印证这些变更在 1.0 中的实际落地方式，帮助你在升级或定制 Bulma 前建立完整的版本认知。

版本总览：如何阅读这份 Changelog

CHANGELOG.md 按版本号倒序组织，当前仓库 package.json 中声明的版本为 1.0.4，与 changelog 顶部条目一致。每条记录通常分为以下几类小节：

• New Features：新增的类、修饰符、Sass 变量与 mixin；
• Improvements / Bug Fixes：行为改进与缺陷修复，多数关联 issue 编号（如 Fix #3824）；
• Breaking change / BREAKING：不兼容变更，升级时必须关注；
• Deprecation warning：文件迁移或类废弃，给出替代导入路径。

从源码结构看，1.0 的构建流程也印证了 changelog 中提到的构建细节：package.json 的 scripts 使用 sass --style=expanded --source-map bulma.scss css/bulma.css 构建主包，再用 postcss 配合 cssnano 压缩，并通过 version-* 脚本构建四个衍生版本（见 css/versions/）。

1.0.4：排版类与 CSS 变量根可配置

1.0.4 的变更聚焦于两个新特性与两处修复：

• 新特性：新增排版类 .has-text-weight-extrabold（#3937）；
• 新特性：让 CSS 变量的声明根（root）可配置（#3906，修复 #3895）——这意味着 CSS 变量不再只注入到默认挂载点上，可以适配自定义的变量作用域；
• Bug 修复：改进 outlined 按钮的颜色加载版本（#3963）、修正 hero is-bold 颜色变体的语法（#3950）；
• 文档修复：修复 .skeleton-toggler 相关问题（#3916）。

1.0.3：恢复被误删的 Sass 变量

1.0.3 是一次“回归修复”版本，重点恢复 1.0 重写过程中丢失的定制能力：

• 恢复 $easing、$radius-rounded、$speed 三个 Sass 变量的使用（#3842）；
• 迁移代码以规避 Sass 1.80 对全局内置函数的弃用警告（#3920）；
• 新增 $duration Sass 变量（#3945）；
• 补上缺失的非压缩版 bulma-prefixed 产物（#3822）、为 helpers 类补上前缀（#3805）。

最后一项与前缀机制直接相关：1.0 允许给所有 Bulma 类添加前缀，让 .button 变成 .my-prefix-button。该机制由 Sass 变量 $class-prefix 实现，在 sass/utilities/initial-variables.scss 中默认为空字符串：

$class-prefix: "" !default;

预构建的前缀版入口 versions/bulma-prefixed.scss 仅 6 行，通过 @use "../sass" with ($class-prefix: "bulma-") 完成整个框架的类名前缀化，产物位于 css/versions/bulma-prefixed.css：

@use "../sass" with (
  $class-prefix: "bulma-"
);

1.0.2：Smart Grid 增强与表单变量扩充

1.0.2 是 1.0 系列中改进最密集的一版：

改进：

• Smart Grid 的 is-col-min 支持到 32（修复 #3829）；
• Column 间距不再需要 is-variable 修饰符；
• 可用 radios / checkboxes 类组织单选与复选按钮组；
• Container 元素新增 is-max-tablet 修饰符；
• 颜色与背景 helpers 新增 currentColor 与 inherit 取值；
• Section 可用 is-fullheight 修饰符获得 100vh 最小高度；
• 新增 SCSS 变量：$input-border-style、$input-border-width、$label-spacing、$field-block-spacing；
• 新增 CSS 变量：--bulma-input-border-style、--bulma-input-border-width、--bulma-label-color、--bulma-label-spacing、--bulma-label-weight、--bulma-help-size、--bulma-field-block-spacing。

Bug 修复：恢复 $scheme-h、$scheme-s、$dark-l、$light-l 的可覆盖能力（#3824）、补齐剩余 logical properties（#3830）、保证 12 列布局占满全宽（#3743）、恢复变量列（#3799）、恢复 --bulma-column-gap CSS 变量（#3846）、限定 has-background helpers 只影响所应用的元素（#3775）、恢复 $navbar-burger-color 的使用（#3757）等。

1.0.1：构建产物修复与模块化文档

1.0.1 主要修复 1.0.0 发布后暴露的工程问题：

• .select 颜色问题（#3755）；
• “No Dark Mode” 版本遗漏 helpers（#3736）；
• 构建非压缩版本（#3744）；
• 允许嵌套固定网格（fixed grids，#3747）；
• 移除未使用的 .skeleton 类（#3759）；
• 修正圆角按钮的水平内边距（#3786）。

文档层面则更新了模块化使用方式说明（#3729）与 @prefers-reduced-motion 的使用（#3785）。其中“模块化”能力在仓库中对应 sass/ 目录下的 _index.scss 分模块导出结构，以及 versions/bulma-no-helpers.scss、versions/bulma-no-dark-mode.scss 等入口文件——例如 versions/bulma-no-dark-mode.scss 通过 @forward 逐个转发 utilities、base、elements 等模块并只引入 themes/light，正是 “no dark mode” 版本的实现方式。

1.0.0：基于 Dart Sass 的全面重写

这是 changelog 中唯一单独展开说明的重写版本，值得逐点理解。官方描述：Bulma v1 是一次基于 Dart Sass（Sass 的主实现）的完整重写，但迁移被刻意做到“尽可能无痛”。

不变的部分：HTML 标记零改动

所有 HTML 片段保持不变。如果直接使用预编译的 CSS，只需把 bulma@0.9.4/css/bulma.min.css 换成 bulma@1.0.0/css/bulma.min.css，页面即可继续工作（外观会略有差异）。这一点是 1.0 最重要的兼容性承诺。

变化的部分：CSS Variables 取代字面量

1.0 的核心变化是：用 CSS 变量取代颜色字面量。例如输出从 color: hsl(171deg, 100%, 41%) 变为 color: var(--bulma-primary)。直接后果是：你不再需要 Sass 就能用纯 CSS 定制 Bulma——这一点在仓库中有明确佐证：sass/utilities/css-variables.scss 负责生成 :root 上的 --bulma-* 变量，而 sass/utilities/mixins.scss 中的 mixin 普遍通过 cv.getVar("...") 读取这些变量，例如 arrow mixin 的 transition-duration 就取自 getVar("duration")，与 1.0.3 中补回的 $duration 变量相呼应。

构建链路上，package.json 的 devDependencies 使用 sass（即 Dart Sass）与 cssnano/postcss-cli，build-bulma 脚本直接编译根目录的 bulma.scss。

新增能力：主题、暗色模式、色板、骨架屏与前缀

1.0.0 引入了五个此前不存在的能力：

1. Themes（主题）：一个主题是上下文内的一组 CSS 变量集合，是定制 Bulma 的推荐方式。对应源码 sass/themes/ 目录下的 light.scss、dark.scss 与共享的 setup.scss；
2. 暗色模式主题：以主题形式内置。从 sass/themes/dark.scss 可以确认其实现方式：dark-theme mixin 通过 register-vars 覆写 scheme-main-l（9%）、background-l（14%）、text-l（71%）等亮度参数，并对 $colors 中的每个颜色重新生成方案内颜色（generate-on-scheme-colors）。这印证了 0.8.0 时期提出的“交换 scheme 变量即可实现暗色模式”的思路在 1.0 中升级为独立主题；
3. Color Palettes（色板）：为 7 个主色各创建了色板（light/dark 系列）；
4. Skeleton loaders（骨架屏）：既可作为独立组件，也可作为其他组件的变体。对应 sass/base/skeleton.scss 中的 .is-skeleton、.has-skeleton 等类（在 1.0.1 中清理了未使用的 .skeleton 类）；
5. 类名前缀：如上文 $class-prefix 所述，预构建的前缀版本即 css/versions/bulma-prefixed.css。

0.9.x：断点系统与 RTL 支持成熟

进入 1.0 之前，0.9 系列奠定了大量 1.0 沿用的基础设施：

0.9.4（0.9 系列最后一版）：

• 响应式按钮：按钮尺寸随断点变化（#1572）；
• 新 mixin @mixin between：接收两个断点值，输出二者之间的媒体查询；
• $breakpoints Sass map：命名断点及其类型（from、until 或两者）；
• @mixin breakpoint：基于新 map 输出媒体查询。

后三项在当前 sass/utilities/mixins.scss 中仍可看到：between($from, $until) 定义于第 280 行，breakpoint($name) 定义于第 364 行——这是 0.9.4 引入、1.0 继续沿用的断点体系。该版本还引入了 Cypress 测试（#3436），仓库中对应 cypress/e2e/ 下的 e2e 用例目录。

0.9.0（0.9 系列的重要节点）：

• 废弃警告：base/helpers.sass 移入独立的 /helpers 目录，应改导入 sass/helpers/_all.sass（对应现仓库 sass/helpers/）；list 组件被删除；
• RTL 支持：将 $rtl 设为 true 即可构建 RTL 版 Bulma，依赖 =ltr、=rtl、=ltr-property、=ltr-position 四个 mixin，并随包提供 bulma-rtl.css；
• Spacing helpers：m* / p* 前缀 + 方向后缀（t/r/b/l/x/y）+ 6 档数值后缀的组合体系（如 mt-*、pb-*、mx-*），并加入浅色/深色文字与背景 helpers。当前实现位于 sass/helpers/spacing.scss。

0.9.2 有一次小型 breaking change：所有 Sass placeholders（%control、%unselectable、%arrow、%block、%delete、%loader、%overlay）从 utilities/mixins 移入独立的 utilities/extends 文件（现 sass/utilities/extends.scss）。若直接从 utilities/mixins 导入 placeholder 需要更新导入；而导入 bulma.sass 整体的用户不受影响。该版本还带来 .is-ghost 按钮与 icon-text 组件。

0.8.0：颜色体系的重大升级

0.8.0 是 changelog 中记录最详尽的 0.x 版本，其多项机制是理解 1.0 颜色系统的前置知识：

表单控件变大：控件与按钮高度提升到 2.5em。若想回退，可设置：

$control-height: 2.25em
$control-padding-vertical: calc(0.375em - #{$control-border-width})
$control-padding-horizontal: calc(0.625em - #{$control-border-width})
$button-padding-vertical: calc(0.375em - #{$button-border-width})
$button-padding-horizontal: 0.75em

Light / Dark 颜色：每个主色（primary、info、success、warning、danger）都拥有 *-light 与 *-dark 版本，由两个颜色函数计算：

• findLightColor()：找某颜色的浅色版本；
• findDarkColor()：找某颜色的深色版本。

浅色版本被 button 元素使用，light/dark 版本被 message 组件使用。这些函数在当前仓库 sass/utilities/functions.scss 中实现（bulmaFindLightColor / bulmaFindDarkColor），并在 mergeColorMaps() 内被自动调用补齐缺失的颜色分量。

4 值颜色 map：$colors 的每个值变为最多 4 个分量的 map，例如 "info" 对应 ($info, $info-invert, $info-light, $info-dark)。自定义 $custom-colors 时每个值可以只提供 1 到 4 个分量，Bulma 会自动计算其余分量，官方示例：

$custom-colors: (
  'lime': (
    lime,
  ),
  'tomato': (
    tomato,
    white,
  ),
  'orange': (
    $orange,
    $orange-invert,
    $orange-light,
  ),
  'lavender': (
    $lavender,
    $lavender-invert,
    $lavender-light,
    $lavender-dark,
  ),
);

Scheme 变量：新增 6 个 $scheme 派生变量——$scheme-main、$scheme-main-bis、$scheme-main-ter`、`$scheme-invert、$scheme-invert-bis`、`$scheme-invert-ter，替换代码库中的 $white`/`$black` 引用，从而只需交换值即可实现暗色模式：

$scheme-main: $black
$scheme-invert: $white
// etc.

这也是代码库普遍引用派生变量（$text、$background、$border）而非初始变量（$grey、$grey-lighter、$grey-darker）的原因：更新派生变量会直接影响所有元素与组件。默认值方面，$scheme-main: $white、$scheme-main-bis: $white-bis、$scheme-main-ter: $white-ter、$scheme-invert: $black、$scheme-invert-bis: $black-bis、$scheme-invert-ter: $black-ter。其余派生变量按 findColorInvert() / findLightColor() / findDarkColor() 逐个生成（如 $primary-invert: findColorInvert($primary)、$info-light: findLightColor($info) 等，覆盖 primary/info/success/warning/danger/light/dark）。

其他值得注意的 0.8.0 变更：初始色更新为 $green: hsl(141, 53%, 53%)、$cyan: hsl(204, 71%, 53%)、$red: hsl(348, 86%, 61%)；$control-height: 2.5em；$textarea-min-height: 8em、$textarea-max-height: 40em；$image 新增 .is-fullwidth 修饰符。

0.7.0 与 0.7.5：可定制性的扩展期

0.7.0 引入两项关键定制开关：

• $widescreen-enabled 与 $fullhd-enabled：可设为 false 关闭对应断点；
• $custom-colors 与 $custom-shades：允许把自己的颜色与灰阶并入 Bulma 的 $colors 与 $shades map。

其余改进包括 .has-background 块级背景 helpers、$card-header-background-color 等卡片背景变量、.is-expanded 用于 .buttons.has-addons。该版本还以表格形式列出了大量变量默认值变更（如 $gap 从 32px 到 64px、$radius 从 3px 到 4px、$hr-height 从 1px 到 2px）以及 breadcrumb、message、navbar、title 等文件的新增/移除变量明细，是升级 0.7 时逐一核对默认值的依据。

0.7.5 的要点：

• 支持通过 $title-family、$subtitle-family、$button-family 覆盖字体：

$title-family: 'Georgia', serif;

• 废弃警告：form.sass 移入独立的 /form 目录，应改导入 sass/form/_all.sass（对应现仓库 sass/form/）；
• 新增变量横跨 base（$body-font-size、$small-font-size、$pre-padding 等）、components（$card-header-padding、$menu-list-link-padding、$pagination-item-margin 等十余个）、elements 与 grid 层。

0.5.0：变量命名体系确立

0.5.0 确立了沿用至今的变量命名系统：component-subcomponent-state-property。该版本附带了一张大型“重命名对照表”，把旧变量统一追加 -color 后缀，例如：

From	To
$card	$card-color
$navbar-item-hover	$navbar-item-hover-color
$input-focus-border	$input-focus-border-color
$pagination-current-border	$pagination-current-border-color
$box-background	$box-background-color

从 0.5.0 起，自定义 Bulma 的变量名与当前 docs/_data/variables/ 中自动生成的变量文档一致。该版本还新增了 .is-shadowless helper 与 tag 列表特性。

0.4.0 至 0.2.x：结构成型期

• 0.4.0：默认字号定为 16px；新增 .field 元素（.control 语义改变）；新增 .pagination 尺寸；新增 $fullhd 断点（1344px）；
• 0.4.3：新版带 dropdown 的 navbar、Breadcrumb 组件、响应式 is-*-touch 列类；
• 0.4.4：$gap 变量可定制断点与 container 间距；.container 新增 .is-widescreen、.is-fullhd 修饰符；
• 0.3.0：全面改用 rem 与 em；
• 0.2.0：引入模块化（modularity）与 grid 目录，此后 Bulma 的分目录组织方式基本定型（与现仓库 sass/ 下 base/elements/components/form/grid/layout/helpers 的结构对应）。

0.0.x：早期破坏性变更密集期

早期版本的 breaking change 对理解类名演进最有价值，changelog 以加粗 BREAKING 标记：

• 0.0.23：bulma 目录更名为 sass（避免 bulma/bulma 冗余路径）；variables.sass 移入 /utilities；确立“elements 只有一个类、components 至少一个子类”的结构规则；所有变量加上 !default，允许在导入 Bulma 之前覆盖默认值——这是 Bulma 定制模式的起点；
• 0.0.19：.tile 诞生；.is-third 更名为 .is-one-third、.is-quarter 更名为 .is-one-quarter；
• 0.0.18：.is-text-* 更名为 .has-text-*（即现在的文字颜色 helpers 命名）；新增 12 列与 *-full 列类；
• 0.0.26：.navbar 更名为 .level、.header 更名为 .nav；新增 .modal-card；
• 0.0.28：.control.is-grouped 改为以 .control 元素作为直接子级。

升级路径建议：从 Changelog 提炼的操作清单

综合上述条目，按不同起点升级时最需要注意的事项可以归纳如下（均以 CHANGELOG.md 原文为准）：

从 0.x 升到 1.0：

1. 直接使用者：HTML 无需改动，替换预编译 CSS 即可，但需接受外观微调；
2. Sass 定制者：0.9 时代的 @import 风格覆盖（先 $var: ... 再 @import）在 1.0 的模块化 Sass 下需改用 @use ... with (...)，定制方式详见 docs/documentation/customize/with-sass.html；
3. 曾导入 base/helpers.sass、form.sass 的用户，在 0.9.0 / 0.7.5 时就应迁移到 sass/helpers/ 与 sass/form/ 目录；
4. 曾从 utilities/mixins 直接导入 placeholder（%control 等）的用户，需改导入 utilities/extends（0.9.2 的 breaking change，文件现为 sass/utilities/extends.scss）；
5. 若项目对 1.0 新特性有取舍，可考虑仓库提供的替代版本：无暗色模式版（versions/bulma-no-dark-mode.scss）、无 helpers 版（versions/bulma-no-helpers.scss）及其前缀版（versions/bulma-no-helpers-prefixed.scss）、全前缀版（versions/bulma-prefixed.scss）。

在 0.x 内跨版升级：重点核对 0.8.0 的 $colors 4 值 map 变化、0.6.0 中 $link 进入 $colors（.button.is-link 变为彩色按钮，下划线按钮改用 .is-text）、以及 0.5.0 的变量重命名表。

小结

CHANGELOG.md 呈现出 Bulma 清晰的演进主线：0.0.x 建立目录结构与 !default 定制模式，0.3–0.4 定型 .field/.control 与断点体系，0.5 确立变量命名规范，0.8 完成颜色体系重构（4 值 map、scheme 变量），0.9 补齐断点 mixin、RTL 与 spacing helpers，1.0 则用 Dart Sass + CSS 变量 + 主题机制完成重写，并以 1.0.1–1.0.4 四个补丁版逐步修复重写带来的回归（丢失的 Sass 变量、缺失的构建产物、helpers 前缀等）。对使用者而言，这份 changelog 既是升级检查清单，也是追溯某个类、变量或 mixin 引入时点的权威索引。