Windows环境Sass编译CSS编码异常解决方法

在 Windows 系统下使用 Sass 编译 SCSS 文件时，即便已在文件开头添加了 @charset "UTF-8"; 声明，编译过程依然会报错，提示 Invalid GBK character。许多开发者首先会怀疑编码声明有误，但实际上，根本原因在于 Ruby 默认使用 GBK 编码解码文件，尚未进入 Sass 解析阶段便已崩溃。

直接修改 engine.rb 才是正确的解决方案，否则 @charset "UTF-8"; 声明形同虚设。

为什么 @charset "UTF-8" 加了也没效

这行声明仅作为标签，告知浏览器“此 CSS 文件采用 UTF-8 编码”，但它无法改变 Ruby 读取 SCSS 文件时的行为。错误信息中的 Invalid GBK character "xE5" 已明确显示：Ruby 正在用 GBK 解码一个 UTF-8 编码的字节流，解码失败直接报错退出。此时 @charset 声明仍位于文件开头，尚未被读取。

此外，还有几个常见陷阱需注意：

• @charset "UTF-8"; 前面如果存在空格、空行或 BOM（尤其是记事本默认添加 BOM），则等同于无效
• 写成小写 utf-8，旧版 Sass 会直接忽略
• 试图在 .scss 文件中添加一行声明来修复 Ruby 层的读取行为，逻辑上本身就不正确

必须修改 engine.rb 设置 Ruby 默认编码

在 Windows 环境下，Ruby 的默认编码 Encoding.default_external 为 GBK，而非 UTF-8。要使 Ruby 使用 UTF-8 打开文件，必须手动修改 Sass gem 中的 engine.rb 文件。

具体操作步骤如下：

• 首先运行 sass -v 确认实际版本，然后使用 gem which sass 或 bundle show sass 找到真实路径，不要仅依赖系统 Ruby 安装目录
• 典型路径：Windows 下类似 C:Ruby25-x64librubygems2.5.0gemssass-3.7.3libsassengine.rb，macOS 下类似 /usr/local/lib/ruby/gems/3.0.0/gems/sass-3.7.4/lib/sass/engine.rb
• 如果使用 Koala 或 CodeKit 等工具，它们自带 Ruby 环境，需要进入安装目录寻找内嵌 gem，例如 D:Koalarubygemsgemssass-3.4.9libsassengine.rb
• 在 engine.rb 中，找到所有 require 语句之后、module Sass 或 class Sass::Engine 定义之前，插入一行：Encoding.default_external = Encoding.find('utf-8')

.scss 文件本身必须满足三个硬条件

修改 engine.rb 仅是第一步，SCSS 文件本身的编码规范也必须跟上，遗漏任何一条都会导致修复链断裂。

• 使用 VS Code、Sublime 或 WebStorm 保存为 UTF-8 without BOM，切勿选择“UTF-8 with BOM”
• @charset "UTF-8"; 必须是文件的第一行、第一个字符，前面不能有任何内容（包括空格、注释、BOM）
• 项目路径绝对不能包含中文，例如 D:我的项目srcstyle.scss 会触发 Ruby 编码异常；可临时改为 D:my-projectsrcstyle.scss 以验证是否为此原因

编译后 .css 仍乱码？检查三处 UTF-8 是否统一

即使 SCSS 成功编译，浏览器加载时仍可能出现二次乱码。此时需检查以下三点是否统一：

• HTML 中必须包含 ，并置于 靠前位置
• 编译输出的 .css 文件头部必须有 @charset "UTF-8";（注意这是输出文件，非源 SCSS）
• 确保 Web 服务器返回的 HTTP Content-Type header 包含 charset=utf-8，例如 text/css; charset=utf-8

最容易被忽略的两个问题是：项目路径含中文以及 engine.rb 插入位置不对——前者会导致 sass --watch 直接崩溃，后者使整段设置完全不生效。排查时建议优先确认这两个点。