Shopify Polaris CSS 语法错误导致 Vite 构建失败问题解析

在 Shopify 的 Polaris 设计系统（版本 13.9.2）中，存在一个影响 Vite 构建流程的 CSS 语法问题。该问题主要出现在 Polaris 编译后的 CSS 文件中，表现为多处使用了非标准的双分号语法（;;），这会导致使用 Tailwind CSS v4 的项目在构建时失败。

问题现象

当开发者在 Vite 项目中同时使用 Polaris 和 Tailwind CSS v4 时，构建过程会抛出"Unexpected semicolon"错误。错误信息明确指出问题来源于 Polaris 的编译后 CSS 文件（styles.css），其中包含多处非标准的分号使用。

技术分析

根本原因

问题源于 Polaris 编译后的 CSS 文件中存在多处冗余的分号。例如：

.Polaris-VideoThumbnail__ProgressBar {
  width: 0.0625rem !important;;
  height: 0.0625rem !important;;
  /* 其他属性 */
}

这种双分号语法虽然在某些 CSS 解析器中可能被容忍，但在 Tailwind CSS v4 使用的 Lightning CSS 解析器中会被视为语法错误。

影响范围

该问题影响所有使用以下技术栈组合的项目：

• @shopify/polaris ≥13.9.2
• @tailwindcss/vite
• Tailwind CSS v4

临时解决方案

开发者可以采取以下临时解决方案：

1. 手动修复 CSS 文件：
   • 复制 Polaris 的 styles.css 文件到项目本地
   • 移除所有多余的分号（将;;替换为;）
   • 通过 @import 引入修改后的文件

@import './modified-polaris.css' layer(polaris);

2. 降级 Tailwind CSS： 暂时回退到 Tailwind CSS v3，该版本使用的解析器对双分号语法更为宽容。

长期解决方案

Shopify 团队需要在 Polaris 的构建流程中修复 CSS 生成逻辑，确保输出的 CSS 符合标准语法规范。这包括：

1. 更新 CSS 预处理工具链
2. 添加 CSS 语法校验步骤
3. 确保构建产物符合 W3C CSS 标准

最佳实践建议

对于遇到此问题的开发者，建议：

1. 关注 Polaris 的版本更新，及时升级到修复此问题的版本
2. 在项目中建立 CSS 质量检查流程，避免类似问题
3. 考虑使用 PostCSS 等工具对第三方 CSS 进行预处理

该问题虽然表现为构建错误，但本质上反映了前端生态中不同工具链对 CSS 标准遵循程度的差异。随着前端工具链的不断演进，对标准语法的严格检查将成为趋势，这也促使各开源项目需要更加注重输出产物的规范性。