Vue2 老项目里，SCSS 和图片路径的“相爱相杀”——从踩坑到优雅

Vue2 老项目里，SCSS 和图片路径的“相爱相杀”——从踩坑到优雅

“哥，我背景图又 404 了！”
“你路径写对了吗？”
“我写了../../../assets/img/bg.png啊！”
“……你数数几个点？”

如果你也在 Vue2 的老仓库里搬过砖，上面这段对话八成耳熟。今天咱们不聊高深的设计模式，就聊“怎么让 SCSS 里的图片路径像 JS 模块一样省心”。别小看这点小事，路径写错，样式崩；路径写死，重构哭。Webpack 别名（alias）本是一剂良药，却常被我们用成了泻药。下面这段路，我陪你从头踩到尾，坑边插满 flag，保证你下次不再“点数”。

alias 不是“小老鼠”，它是任意门

先给 alias 正个名：它不只是import Button from '@/components/Button'的语法糖，而是 Webpack 在任何请求资源时都会走的“任意门”。
门后长啥样？打开vue.config.js（或者你手动的webpack.base.conf.js）瞄一眼：

// vue.config.jsconstpath=require('path');module.exports={chainWebpack:config=>{config.resolve.alias.set('@',path.resolve(__dirname,'src')).set('~assets',path.resolve(__dirname,'src/assets')).set('~img',path.resolve(__dirname,'src/assets/img'));}};

上面三行代码，给项目造了三条捷径：

注意，我故意把后两个写成“~”开头，就是为了和“@”区分——在 SCSS 里，Webpack 只会把“~”当成“这是个别名，给我解析”的信号。
换句话说：

• 在 JS 里，@/assets/img/bg.png能跑；
• 在 SCSS 里，~assets/img/bg.png才稳。

记不住？就把“~”想成“波浪号提醒 Webpack：别偷懒，给我找别名”。

SCSS 引图片的“五连鞭”

先把祖传代码摆出来，看看你都写过哪一招：

1. 原始社会：background: url('../assets/img/bg.png');
   项目目录一深，点对点相对路径直接变“点滑滑梯”，少一个点，全家 404。

2. 引号纠结体：background: url("./assets/img/bg.png");
   加不加引号 Webpack 都认，但 sass-loader 7.x 之前有个彩蛋：
   带引号的路径不会被resolve-url-loader再加工，结果生产环境路径错得离谱。

3. 波浪号尝鲜：background: url('~@/assets/img/bg.png');
   乍一看没问题，实则“~@”叠 buff 多余：sass-loader 看到“~”就去调 alias 解析，解析完返回的是绝对路径，前面再加“@”反而会让它以为“哟，还有一层别名？”——于是给你抛Can't find module的大红字。

4. 变量玩家：

   $imgPath: '~img'; background: url('#{$imgPath}/bg.png');

   用 Sass 变量拼接路径，本地跑得好好的，一上生产 404？
   八成是css-loader的esModule:false和sass-loader的sassOptions.outputStyle没对齐，变量替换发生在 Sass 编译之后，Webpack 来不及再帮你做 alias 解析。

5. 终极形态—— alias 直引：

   background: url('~img/bg.png');

   干净、利落、无副作用，只要保证 sass-loader 和 css-loader 版本别太老，这就是官方推荐的“正确答案”。

实战：让 sass-loader 乖乖叫“爸爸”

下面这份配置，我连续睡了三年生产环境，没翻过车。直接抄，不亏。

// vue.config.jsconstpath=require('path');module.exports={css:{loaderOptions:{// 1. 给 sass-loader 塞全局变量，省的每个文件手动 @importsass:{prependData:`@import "~@/styles/var.scss"; @import "~@/styles/mixin.scss";`}}},chainWebpack:config=>{// 2. 先清掉 Vue 内置的 svg 处理，后面想自己玩 inline 请随意config.module.rules.delete('svg');// 3. 加 aliasconfig.resolve.alias.set('@',path.resolve(__dirname,'src')).set('~img',path.resolve(__dirname,'src/assets/img')).set('~icons',path.resolve(__dirname,'src/assets/icons'));// 4. 保证 url-loader 对 jpg png gif 不抽风config.module.rule('images').test(/\.(png|jpe?g|gif)(\?.*)?$/).use('url-loader').loader('url-loader').options({limit:8192,// 8k 以下转 base64，以上吐文件name:'img/[name].[hash:8].[ext]',publicPath:process.env.NODE_ENV==='production'?'https://cdn.xxx.com/':'/'});}};

注意第 4 步的publicPath：

• 本地开发填'/'，保持相对路径；
• 生产环境直接写 CDN 域名，上线后图片自动走加速。

一条配置，开发/生产双吃，再也不用给运维同学发“帮忙改下 nginx 反向代理”的工单。

翻车现场：Alias 不生效的 4 种“死法”

1. 文件层级太深
   目录结构：

   src └─ views └─ user └─ profile └─ index.vue └─ index.scss

   你在index.scss写：

   background: url('~img/bg.png');

   编译报错Module not found？
   十有八九是vue-cli默认的resolve.modules只认['node_modules', 'src']，而你的img目录在src/assets下。
   解决：把~img的 alias 指到精确路径，或者把src/assets再塞进resolve.modules，别让它自己猜。

2. 用了变量却忘了 “#{}”
   sass 变量如果直接放在url()里，必须插值：

   $icon: '~icons/close.svg'; background: url($icon); // × 变量当字符串，Webpack 不解析 background: url('#{$icon}'); // √ 插值后变成字面量，再走 alias

3. 生产环境多了层../
   本地跑得好好的，build 之后路径多了../../，浏览器直接 404。
   原因：
   extract-text-webpack-plugin（或mini-css-extract-plugin）抽离出来的 CSS 文件层级变了，而publicPath没配。
   解决：
   在vue.config.js里加

   css:{extract:{publicPath:'../../'}}

   或者干脆把图片全扔 CDN，别让它们走相对路径。

4. sass-loader 版本“回光返照”
   老项目升级vue-cli后，发现以前能跑的路径全挂。
   一查 package-lock，sass-loader 从 7.x 升到 10.x，默认开启了sassOptions.outputStyle: compressed，导致resolve-url-loader收不到完整路径。
   解决：

   loaderOptions:{sass:{sassOptions:{outputStyle:'expanded'// 先展开，再交给 resolve-url-loader}}}

Debug 三板斧：肉眼定位 → 机器验证 → 自动化

1. 肉眼定位
   在 SCSS 里故意写错：

   background: url('~img/nonexist.png');

   编译时控制台会抛出绝对路径，一眼看清 Webpack 到底解析到哪儿。
   把路径复制出来，在磁盘里ls一下，90% 的拼写错误当场现形。

2. 机器验证
   装个webpack-bundle-analyzer：

   npmi -D webpack-bundle-analyzer

   // vue.config.jsconstBundleAnalyzer=require('webpack-bundle-analyzer').BundleAnalyzerPlugin;module.exports={configureWebpack:{plugins:[newBundleAnalyzer({analyzerPort:8888})]}};

   build 后浏览器会自动打开一张“资源地图”，图片有没有被打包、体积多大、路径长啥样，一目了然。

3. 自动化
   给 SCSS 封装一个bg()mixin，内部自动拼路径，顺便吐调试信息：

   // mixin.scss @mixin bg($name, $ext: 'png') { // 调试阶段输出路径 @debug '~img/#{$name}.#{$ext}'; background-image: url('~img/#{$name}.#{$ext}'); } // 使用 .box { @include bg('login-bg', 'jpg'); }

   开发时npm run serve会在终端打印：

   DEBUG: ~img/login-bg.jpg

   上线前把@debug一行注释掉即可，干净无残留。

开发体验锦囊：把“路径”写成“语法糖”

1. 全局变量一把梭

   // var.scss $imgDir: '~img'; $iconDir: '~icons';

   以后换 CDN 只用改这一行，所有组件自动生效。

2. 万能 mixin 之 bg-img

   @mixin bg-img($name, $size: cover, $repeat: no-repeat) { background: url('~img/#{$name}') 0 0 / $size $repeat; }

   调用：

   .hero { @include bg-img('hero.jpg', 100% 100%); }

   设计师一天改三回图名？让 UI 小伙伴自己替换图片即可，CSS 一行不动。

3. VS Code 路径提示
   装插件path-alias，再配.vscode/settings.json：

   "pathAlias.aliasMap":{"~img":"/src/assets/img","~icons":"/src/assets/icons"}

   写样式时敲~i自动弹出补全，妈妈再也不用担心我拼错单词。

CDN 与世界：生产环境如何“无痛切域名”

1. 环境变量注入

   // vue.config.jsconstpublicPath=process.env.VUE_APP_CDN||'/';module.exports={css:{loaderOptions:{sass:{prependData:`$cdn: "${publicPath}";`}}}};

   // mixin.scss @mixin cdn-bg($name) { background-image: url($cdn + 'img/' + $name); }

   本地.env.development：

   VUE_APP_CDN=/

   生产.env.production：

   VUE_APP_CDN=https://cdn.xxx.com/

   一条npm run build自动把域名拼进去，运维切 CDN 只要改环境变量，无需重新打包。

2. 缓存戳
   图片更新后 CDN 缓存不刷新？把文件名哈希打开即可，上面url-loader已经配了[hash:8]，文件一变，名就变，缓存自动失效。

骚操作番外篇：SVG 内联、批量引入、PostCSS 自动优化

1. SVG 直接内联，省一次 HTTP
   用svg-url-loader把 SVG 变成 utf-8 编码：

   config.module.rule('svg').use('svg-url-loader').loader('svg-url-loader').options({encoding:'utf8',limit:0// 全部转内联});

   SCSS 里：

   .icon-close { background: url('~icons/close.svg') center / contain no-repeat; }

   构建后 SVG 被转成url("data:image/svg+xml,%3Csvg ...")，浏览器不再额外发请求，完美。

2. require.context 批量引入雪碧图
   图标太多，一一 import 烦？写个 Webpack 脚本：

   // src/assets/icons/index.jsconstreq=require.context('./',false,/\.svg$/);req.keys().forEach(req);

   然后在入口main.js引一次即可，Webpack 会自动把目录下所有 SVG 打包，SCSS 里想用谁就用谁。

3. PostCSS 自动压缩背景图
   装插件：

   npmi -D postcss-url

   // postcss.config.jsmodule.exports={plugins:[require('postcss-url')({url:'inline',// 小于 8k 自动转 base64maxSize:8})]};

   构建阶段再优化一遍，小图直接内联，大图保持外链，无需手动干预。

收个尾：把“路径”做成团队规范

1. README 里画一张“资源地图”

   src ├─ assets │ ├─ img → ~img │ ├─ icons → ~icons │ └─ fonts → ~fonts

   新成员第一天 clone 仓库就能看懂，不用挨个问“师兄背景图放哪”。

2. Code Review 加一条“路径 linter”
   用stylelint插件stylelint-declaration-strict-value禁止出现'../assets'这样的相对路径：

   {"rules":{"declaration-strict-value":["/^url/",{"ignoreValues":["~"]}]}}

   一旦有人手滑写../../，CI 直接飘红，把问题拦在合并之前。

3. 把 mixin 和变量当成“官方 SDK”维护
   谁新增全局目录，就在var.scss里补一条别名，再补一个对应的 mixin。
   半年后回来看，代码风格依旧整齐，不会像祖传项目那样“一半 alias 一半点点点”。

写到这里，差不多 6 公里长。
下次再看到../../../这种“摩斯密码”，别心软，直接 refactor 成~img/xxx.png，然后对同事摊手：“别名真好用，早换早下班。”

（完）

欢迎来到我的博客，很高兴能够在这里和您见面！希望您在这里可以感受到一份轻松愉快的氛围，不仅可以获得有趣的内容和知识，也可以畅所欲言、分享您的想法和见解。

推荐：DTcode7的博客首页。
一个做过前端开发的产品经理，经历过睿智产品的折磨导致脱发之后，励志要翻身农奴把歌唱，一边打入敌人内部一边持续提升自己，为我们广大开发同胞谋福祉，坚决抵制睿智产品折磨我们码农兄弟！

吾辈才疏学浅，摹写之作，恐有瑕疵。望诸君海涵赐教。望轻喷，嘤嘤嘤

非常期待和您一起在这个小小的网络世界里共同探索、学习和成长。愿斯文对汝有所裨益，纵其简陋未及渊博，亦足以略尽绵薄之力。倘若尚存阙漏，敬请不吝斧正，俾便精进！