Sass.js 快速入门:如何在浏览器中运行 Sass 编译器?SCSS 转 CSS 完全指南
Sass.js 快速入门:如何在浏览器中运行 Sass 编译器?SCSS 转 CSS 完全指南
想在网页里直接编译 SCSS 吗?Sass.js 正是这样一个在浏览器中运行 Sass 编译器的 JavaScript 库。它是 Emscripten 编译版 libsass 的封装 API,只需加载一个 JS 文件,就能在网页端把 SCSS 代码实时转换成 CSS,无需 Node.js、无需后端服务。本文将带你快速上手:从加载方式、编译调用,到 @import 文件处理和常用配置,一篇讲清 Sass.js 的核心用法。
一、Sass.js 是什么?为什么需要它?
Sass.js 的核心理念很简单:把 C++ 写的 libsass 编译器用 Emscripten 转成 JavaScript,然后在浏览器里跑。
它基于 libsass 3.6.2,通过 Web Worker 在后台线程中完成编译,页面不会卡顿。主要适用场景:
- 🌐 在线 SCSS 编辑器 / Playground:用户输入 SCSS,页面即时显示编译出的 CSS
- 📱 纯前端项目:不依赖 Node 构建链,浏览器端按需生成样式
- 🧩 脚手架与插件生态:众多 Webpack、SystemJS、StealJS 插件底层都使用了它
⚠️ 一个重要的使用提醒:Worker 文件压缩后约 4.5MB(gzip 后约 827KB)。如果你在 Node 环境下工作,官方更建议使用性能更好的 node-sass,Sass.js 主要面向浏览器场景。
二、快速上手:3 步在浏览器中编译 SCSS
Sass.js 针对不同运行环境提供了多个构建产物(详见 docs/getting-started.md):
| 文件 | 用途 |
|---|---|
dist/sass.js |
浏览器 Worker API(推荐) |
dist/sass.worker.js |
编译器本体,由上面的 API 自动加载 |
dist/sass.sync.js |
同步 API,主线程运行,适合不支持 Worker 的环境 |
dist/sass.node.js |
Node 下直接编译本地文件的便捷封装 |
1. 引入脚本并创建实例
<script src="dist/sass.js"></script>
<script>
var sass = new Sass();
</script>
2. 调用 compile 编译一段 SCSS
var scss = '$someVar: 123px; .some-selector { width: $someVar; }';
sass.compile(scss, function(result) {
console.log(result.text); // 输出编译好的 CSS
});
3. 读取结果
回调中的 result 对象包含:
status:0表示成功,其他值表示出错text:编译后的 CSS 文本map:SourceMap 信息files:本次编译用到的文件列表
出错时会附带 message、line、column 和人类可读的 formatted 错误信息,方便定位问题。
完整示例可以打开仓库里的演示页面 sass.worker.html,里面有带 @import 的实战用法。
三、Worker API 还是同步 API?如何选型
两种 API 的区别,直接看这张对比表:
| 维度 | Worker API(sass.js) |
同步 API(sass.sync.js) |
|---|---|---|
| 运行位置 | Web Worker 后台线程 | 页面主线程 |
| 并发能力 | ✅ 可多实例并行编译 | ❌ 单例,不支持并发 |
| 文件加载 | 自动,无需手动配置路径 | 单文件包含,无需配置 |
| 适用环境 | 现代浏览器(首选) | 不支持 Worker 的环境(Node、Rhino、Nashorn) |
💡 选型建议:能支持 Web Worker 就用 Worker API,编译不阻塞页面交互,还能同时开多个实例并行编译多个文件。
四、常用编译选项速查
通过 sass.options() 可以设置全局编译选项,也可以在单次 compile() 调用时临时传入。最常用的几项:
| 选项 | 说明 |
|---|---|
style |
输出格式:nested / expanded / compact / compressed(压缩) |
precision |
小数精度,默认 5 位 |
comments |
是否输出内联注释 |
indent / linefeed |
自定义缩进字符与换行符 |
indentedSyntax |
源字符串按 SASS 缩进语法(而非 SCSS)解析 |
sourceMapFile 等 |
一整套 SourceMap 生成开关 |
选项的完整定义位于 src/sass.options.js,各枚举值(如 style 的四种取值)可以在 src/sass.api.js 中看到。
想要体验不同语法特性,可以直接看仓库自带的示例文件 scss/example.scss,它用到了 @import、@mixin、@extend 等典型 SCSS 写法。
五、浏览器里怎么解决 @import 依赖?
这是新手最常卡住的一步。浏览器环境没有真实文件系统,Sass.js 的做法是用 Emscripten 的内存虚拟文件系统,所有路径都会被映射到 /sass/ 目录下。
1. writeFile:把依赖文件写进虚拟文件系统
sass.writeFile('one.scss', '.one { width: 123px; }');
sass.compile('@import "one";', function(result) {
console.log(result.text);
});
2. preloadFiles:批量从服务器预加载
如果依赖文件已托管在服务器上,可以用 Sass.preloadFiles() 一次性下载并注册,避免编译时逐个请求。
3. Importer 回调:拦截任意 import 请求
通过 sass.importer(callback) 可以钩住 libsass 的每个 @import 请求,实现三种高级玩法:
- 动态内容:import 到不存在的文件时,直接返回你拼好的 SCSS 字符串
- 路径重定向:把某个 import 指向虚拟文件系统中的另一个位置
- 按需下载:import 时再从接口拉取内容,实现"懒加载 Mixin"
📦 仓库中的 maps/bourbon.js 和 maps/drublic-sass-mixins.js 就是现成的映射示例——它们把整个 Bourbon 库打包成可直接被 import 的结构,是学习"如何组织第三方 Mixin"的好材料。
六、在 Node 中使用 Sass.js
虽然浏览器才是主战场,但 Sass.js 同样跑在 Node 上。使用 dist/sass.node.js 可以省去手动读写文件的麻烦,它会自动把磁盘文件搬进虚拟文件系统再编译:
var compile = require('sass.js/dist/sass.node');
compile('scss/example.scss', { style: compile.Sass.style.expanded }, function(result) {
console.log(result.text);
});
注意路径必须相对于当前工作目录(process.cwd())。再次提醒:Node 场景下性能优先选 node-sass,Sass.js 的 Node 模式更适合跨环境复用同一套代码的场景。
七、实用建议与参考资料
给新手的 4 条实用建议:
- 浏览器中始终优先使用 Worker API,避免主线程阻塞
- 依赖文件较多时用
preloadFiles批量预载,比逐个writeFile更高效 - 需要自定义 import 逻辑时,先用
sass.importer()打日志观察request对象,再决定如何处理 - 关注
result.status判断成败,出错时打印result.formatted会包含行号定位
仓库内值得阅读的资料:
- 入门指南:docs/getting-started.md
- 完整 API 文档:docs/api.md
- 版本记录:CHANGELOG.md
- 测试用例(可当活文档看):test/test.compile.js、test/test.importer.js
掌握了以上内容,你就可以在任意网页中嵌入一个"活的" Sass 编译器,让 SCSS 到 CSS 的转换完全发生在用户的浏览器里。🚀