在Azure静态Web Apps部署Quasar项目的构建资源加载错误排查

1. 先搞定Vite的路径别名配置 #

Quasar默认给@配置了指向src的别名，如果你习惯用~，可以在quasar.config.js里补充Vite的别名设置，确保资源路径能被正确识别：

// quasar.config.js
module.exports = function (ctx) {
  return {
    build: {
      vitePlugins: [
        {
          name: 'vite-alias-config',
          config: {
            resolve: {
              alias: {
                '~': ctx.srcDir, // 把~绑定到项目src目录
                '@': ctx.srcDir  // 保留默认的@别名，按需使用
              }
            }
          }
        }
      ]
    }
  }
}

2. 针对不同非Vue场景的路径处理方案 #

场景1：原生img标签（优化你现有的new URL方法） #

在组件脚本里处理路径后绑定到原生img的src，比直接写死路径更可靠：

<template>
  <img ref="nativeImg" />
</template>

<script setup>
import { onMounted, ref } from 'vue'
const nativeImg = ref(null)

onMounted(() => {
  if (nativeImg.value) {
    // 用@别名，Vite会自动处理资源的打包路径
    nativeImg.value.src = new URL('@/assets/imgs/embroidery.jpg', import.meta.url).href
  }
})
</script>

场景2：原生元素的背景图（style中的background-image） #

直接在style里写~assets/...无效，得通过动态绑定style的方式处理：

<template>
  <div ref="bgContainer"></div>
</template>

<script setup>
import { onMounted, ref } from 'vue'
const bgContainer = ref(null)

onMounted(() => {
  if (bgContainer.value) {
    const bgUrl = new URL('@/assets/imgs/bg.jpg', import.meta.url).href
    bgContainer.value.style.backgroundImage = `url(${bgUrl})`
  }
})
</script>

场景3：批量处理大量原生资源路径 #

如果有很多原生标签要处理，封装个工具函数能省不少事：

// src/utils/assets.js
export const getAssetUrl = (relativePath) => {
  return new URL(`@/assets/${relativePath}`, import.meta.url).href
}

然后在组件里直接调用：

<template>
  <img ref="productImg" />
  <div ref="bannerDiv"></div>
</template>

<script setup>
import { onMounted, ref } from 'vue'
import { getAssetUrl } from '@/utils/assets'

const productImg = ref(null)
const bannerDiv = ref(null)

onMounted(() => {
  if (productImg.value) productImg.value.src = getAssetUrl('imgs/embroidery.jpg')
  if (bannerDiv.value) bannerDiv.value.style.backgroundImage = `url(${getAssetUrl('imgs/banner.jpg')})`
})
</script>

3. 为啥之前的方法会失效？ #

• Quasar的~别名只在Vue模板的v-bind指令里生效，原生HTML标签的属性不会被Vue/Vite解析，直接写src="~assets/..."会被当成普通字符串，Vite找不到对应资源。
• 相对路径在构建时会因为Vite的资源哈希重命名规则，导致最终路径和预期不符，而new URL结合import.meta.url能让Vite正确追踪资源，生成打包后的正确路径。

4. 替代方案：用Vue的v-bind处理模板内的原生标签 #

如果原生标签是写在Vue模板里的，直接用v-bind:src代替原生src，Vue会自动解析别名：

<template>
  <!-- 方式1：用require解析 -->
  <img :src="require('@/assets/imgs/embroidery.jpg')" />
  <!-- 方式2：直接import资源 -->
  <img :src="productImgUrl" />
</template>

<script setup>
import productImgUrl from '@/assets/imgs/embroidery.jpg'
</script>

注意：这个方法只适用于Vue模板里的标签，纯原生HTML（比如public/index.html里的标签）没法用，这种情况还是得把资源放到public目录用绝对路径。

内容的提问来源于stack exchange，提问作者Qiuzman