@charset "utf-8" 单独不起作用,因 ruby 默认用 gbk 解码文件,需同时修改 engine.rb 中 encoding.default_external = encoding.find('utf-8') 并确保文件 utf-8 无 bom。

只加 @charset "UTF-8" 不够,多数情况下仍会报错。 这个声明是必要条件,但不是充分条件——尤其在 Windows + Ruby Sass 环境下,Ruby 默认用系统编码(如 GBK)读取文件,@charset 只影响 Sass 解析器对文件内容的解释,不改变 Ruby 底层读取时的解码行为。
为什么 @charset "UTF-8" 单独不起作用
常见错误信息如:Syntax error: Invalid GBK character "\xE5",说明 Ruby 在把文件内容传给 Sass 前就解码失败了。此时 Sass 根本没机会看到 @charset 声明。
-
@charset必须放在 SCSS 文件最开头(首行首字符),前面不能有空格、BOM 或注释 - 它只告诉 Sass “接下来的内容按 UTF-8 解”,不改变 Ruby 打开文件时用的编码
- Windows 下 Ruby 2.0+ 默认使用
Encoding.default_external为系统 locale(如GBK),而非UTF-8
必须修改 engine.rb 设置 Ruby 默认外部编码
找到你本地 Sass gem 安装路径下的 engine.rb 文件,典型位置包括:
- Windows:
C:\Ruby25-x64\lib\ruby\gems\2.5.0\gems\sass-3.7.3\lib\sass\engine.rb - macOS:
/usr/local/lib/ruby/gems/3.0.0/gems/sass-3.7.4/lib/sass/engine.rb
在所有 require 语句之后、类定义之前插入一行:
Encoding.default_external = Encoding.find('utf-8')
注意:require 是 Ruby 关键字,不是函数调用,不要加括号;这行代码必须在 require 块结束之后,否则可能被覆盖。
验证是否生效的快速方式
改完后重新运行编译命令,观察错误是否消失。若仍报错,检查以下几点:
- 确认修改的是当前项目实际使用的 Sass 版本对应的
engine.rb(可用sass -v查版本,再查 gem 路径) - 确认编辑保存时文件编码为 UTF-8(无 BOM),某些编辑器(如旧版 Notepad)默认保存为 ANSI/GBK
- 如果用 Koala、CodeKit 等 GUI 工具,它们可能自带独立 Ruby 环境,需进其安装目录找自己的
sassgem 路径,而非系统 Ruby 路径 -
@charset "UTF-8"必须严格写成双引号、全大写UTF-8(虽然 Sass 官方文档写utf-8也接受,但部分旧版本对大小写敏感)
真正起作用的是 Ruby 层面的编码切换,@charset 只是配合项。漏掉任意一环,中文注释都会卡在读取或解析阶段。










