深入解析 Sass 的 `~` 路径问题：为什么你的导入会失败？

当你在 Sass 中写下这样的代码时：

@import '~bootstrap/scss/variables';
@import '~company-design-system/colors';

你以为这是标准语法？真相可能会让你惊讶——Sass 官方编译器从不支持波浪符 ~ 开头的路径解析！

---

问题根源：~ 是社区约定而非官方标准

这个看似普遍的语法实质是前端工具链的"民间约定" ，其诞生背景值得深究：

1. 历史渊源
   ~ 最初由 Webpack 引入，用于简化 node_modules 引用（Webpack 文档说明）

   // Webpack 中 ~ 指向 node_modules
   import '~package/style.css'
   

2. Sass 的立场
   官方明确表示： ~ 不是 Sass 特性

3. 构建工具的差异支持

   工具	是否原生支持 ~	备注
   Webpack	✅	通过 sass-loader 实现
   Vite	❌	需额外配置
   Rollup	❌	需插件支持
   Parcel	✅	内置解析

---

当 ~ 遇到 Vite：典型的报错现场

尝试在 Vite 项目中使用 ~ 导入？你将遭遇：

Error: Can't find stylesheet to import.
  │
1 │ @import '~bootstrap/scss/bootstrap';
  │         ^^^^^^^^^^^^^^^^^^^^^^^^^^^

原因解剖：

1. Vite 的 Sass 处理依赖官方编译器
2. 编译器遇到 ~ 会尝试查找名为 ~bootstrap 的目录
3. 最终在项目根目录查找失败

---

解决方案：sass-tilde-importer

sass-tilde-importer 正是为解决此痛点而生！它能：

1. 智能转换：将 ~package 重写为 node_modules/package
2. 双模兼容：同时支持新旧版 Sass API
3. 零侵入：不修改源码，仅需配置一次

// 基础使用示例
const tildeImporter = require('sass-tilde-importer');

// 新版 Sass (sass.compile)
sass.compile('src/app.scss', { importers: [tildeImporter] });

// 旧版 Sass (sass.render)
sass.render({ importer: [tildeImporter] });

---

Vite 专项配置指南

Vite 5（使用旧版 Sass API）

// vite.config.js
const { defineConfig } = require('vite');
const tildeImporter = require('sass-tilde-importer');

module.exports = defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        // 注意这里没有“s”
        importer: [tildeImporter]
      }
    }
  }
});

Vite 6（使用新版 Sass API）

// vite.config.js
const { defineConfig } = require('vite');
const tildeImporter = require('sass-tilde-importer');

module.exports = defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        // 注意这里有“s”
        importers: [tildeImporter]
      }
    }
  }
});

---

为什么选择这个方案？

1. 精准定位问题
   不依赖 Webpack 等特定工具，专注解决 ~ 解析痛点
2. 无历史包袱
   相比重写导入路径的方案，保持原始代码的纯净性
3. 版本自适应
   自动检测 Sass API 版本，无需手动切换逻辑

---

现在开始修复你的导入路径！

安装命令：

npm install sass-tilde-importer
# 或
pnpm add sass-tilde-importer

效果对比：

- @import '~bootstrap/scss/bootstrap'; // 报错：文件未找到
+ @import '~bootstrap/scss/bootstrap'; // 成功解析！

项目资源：
GitHub：https://github.com/linsk1998/sass-tilde-importer
npm：https://www.npmjs.com/package/sass-tilde-importer

让 ~ 导入不再是构建过程的绊脚石，今天就开始享受无缝的 Sass 开发体验！