静态资源处理

• 相关：公共基础路径
• 相关：assetsInclude 配置选项

将资源导入为 URL

导入静态资源将在其被服务时返回解析后的公共 URL

import imgUrl from './img.png'
document.getElementById('hero-img').src = imgUrl

例如，imgUrl 在开发期间将为 /img.png，并在生产环境构建中变为 /assets/img.2d8efhg.png。

此行为类似于 webpack 的 file-loader。区别在于导入可以使用绝对公共路径（基于开发期间的项目根目录）或相对路径。

• CSS 中的 url() 引用以相同方式处理。

• 如果使用 Vue 插件，Vue SFC 模板中的资源引用将自动转换为导入。

• 常见的图像、媒体和字体文件类型将自动检测为资源。可以使用 assetsInclude 选项 扩展内部列表。

• 引用的资源包含在构建资源图中，将获得哈希文件名，并且可以由插件进行优化处理。

• 字节大小小于 assetsInlineLimit 选项 的资源将内联为 base64 数据 URL。

• Git LFS 占位符会自动排除在内联之外，因为它们不包含其代表的文件的内容。要进行内联，请确保在构建之前通过 Git LFS 下载文件内容。

• 默认情况下，TypeScript 不识别静态资源导入为有效模块。要解决此问题，请包含 vite/client。

通过 url() 内联 SVG

将 SVG 的 URL 传递给 JS 手动构建的 url() 时，变量应包含在双引号中。

import imgUrl from './img.svg'
document.getElementById('hero-img').style.background = `url("${imgUrl}")`

显式 URL 导入

不在内部列表或 assetsInclude 中的资源可以使用 ?url 后缀显式导入为 URL。例如，这对于导入 Houdini Paint Worklets 很有用。

import workletURL from 'extra-scalloped-border/worklet.js?url'
CSS.paintWorklet.addModule(workletURL)

将资源导入为字符串

可以使用 ?raw 后缀将资源导入为字符串。

import shaderString from './shader.glsl?raw'

将脚本导入为工作线程

可以使用 ?worker 或 ?sharedworker 后缀将脚本导入为 Web 工作线程。

// Separate chunk in the production build
import Worker from './shader.js?worker'
const worker = new Worker()

// sharedworker
import SharedWorker from './shader.js?sharedworker'
const sharedWorker = new SharedWorker()

// Inlined as base64 strings
import InlineWorker from './shader.js?worker&inline'

查看 Web 工作线程部分 了解更多详细信息。

public 目录

如果您有以下资源：

• 从未在源代码中引用（例如 robots.txt）
• 必须保留完全相同的文件名（不进行哈希）
• ...或者您只是不想先导入资源才能获取其 URL

那么您可以将资源放在项目根目录下的特殊 public 目录中。此目录中的资源将在开发期间在根路径 / 下提供服务，并将按原样复制到 dist 目录的根目录。

该目录默认为 <root>/public，但可以通过 publicDir 选项 进行配置。

请注意：

• 您应该始终使用根绝对路径引用 public 资源 - 例如，public/icon.png 应该在源代码中引用为 /icon.png。
• 无法从 JavaScript 导入 public 中的资源。

new URL(url, import.meta.url)

import.meta.url 是一个本机 ESM 功能，它公开当前模块的 URL。将其与本机 URL 构造函数 结合使用，我们可以使用 JavaScript 模块中的相对路径获取静态资源的完整解析后的 URL

const imgUrl = new URL('./img.png', import.meta.url).href

document.getElementById('hero-img').src = imgUrl

这在现代浏览器中可以原生使用 - 事实上，Vite 在开发期间根本不需要处理此代码！

此模式还支持通过模板文字使用动态 URL

function getImageUrl(name) {
  return new URL(`./dir/${name}.png`, import.meta.url).href
}

在生产环境构建期间，Vite 将执行必要的转换，以便即使在捆绑和资源哈希之后，URL 仍然指向正确的位置。但是，URL 字符串必须是静态的，以便可以对其进行分析，否则代码将保持原样，如果 build.target 不支持 import.meta.url，则会导致运行时错误

// Vite will not transform this
const imgUrl = new URL(imagePath, import.meta.url).href

不适用于 SSR

如果您使用 Vite 进行服务器端渲染，此模式将不起作用，因为 import.meta.url 在浏览器和 Node.js 中具有不同的语义。服务器捆绑包也不能提前确定客户端主机 URL。