Vite 静态资源处理全解：资源导入、内联策略、public 目录与 new URL 解析机制

本篇技术指南基于 Vite 官方文档 docs/guide/assets.md，系统讲解 Vite 的静态资源（Static Asset）处理体系：如何通过 import 获取资源 URL、使用 ?url/?inline/?no-inline/?raw/?worker 等查询后缀控制资源行为、何时应该使用 public 目录、以及如何用 new URL(url, import.meta.url) 处理动态相对路径。读完本文，你将掌握 Vite 资源管线的完整用法，并能从源码层面理解资源内联、哈希命名和构建期 URL 转换的底层实现。

将静态资源导入为 URL

在 Vite 中，导入一个静态资源，得到的就是它在被服务时解析出的公开 URL：

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

例如，imgUrl 在开发阶段是 /src/img.png，在生产构建后会变成形如 /assets/img.2d8efhg.png 的带哈希文件名。

这种行为的思路类似 webpack 的 file-loader，区别在于：导入既可以使用相对路径，也可以使用基于项目根目录的绝对公开路径（绝对 public 路径）。文档中还列举了以下几条关键行为规则：

• CSS 中的 url() 引用按同样方式处理，即 CSS 里引用的图片、字体等资源也会进入资源图，享受相同的解析、内联与哈希逻辑；
• 如果使用 Vue 插件，Vue SFC 模板中的资源引用会被自动转换成 import；
• 常见的图片、媒体和字体文件类型会被自动识别为资源；内部清单可通过 assetsInclude 选项 扩展；
• 被引用的资源会作为**构建资源图（asset graph）**的一部分，获得带哈希的文件名，并且可以被插件处理以做优化；
• 小于 assetsInlineLimit 选项阈值的资源会被内联为 base64 data URL；
• Git LFS 占位符会被自动排除在内联之外，因为它们不包含所代表文件的真实内容——若希望内联生效，请确保构建前已通过 Git LFS 下载文件内容；
• TypeScript 默认不认识静态资源导入，需要通过引入 vite/client 提供的类型声明来解决。

源码视角：内置资源类型清单与识别逻辑

Vite 内置的资源类型清单定义在 KNOWN_ASSET_TYPES 中，覆盖四大类：

• 图片：apng、bmp、png、jpe?g、jfif、pjpeg、pjp、gif、svg、ico、webp、avif、cur、jxl；
• 媒体：mp4、webm、ogg、mp3、wav、flac、aac、opus、mov、m4a、vtt；
• 字体：woff2?、eot、ttf、otf；
• 其他：webmanifest、pdf、txt。

该清单与 DEFAULT_ASSETS_RE 组合成正则用于模块识别，而 client.d.ts 中为这些扩展名逐一声明了 const src: string 的默认导出模块类型（例如 declare module '*.png'），这就是文档中“引入 vite/client 修复 TS 报错”的原理。

资源的实际加载由 asset.ts 中的 vite:asset 插件完成：其 load 钩子（asset.ts#L223-L294）先判断是否命中 assetsInclude 或 ?url 后缀，然后按环境区分两条路径——开发/非打包环境走 fileToDevUrl，打包构建环境走 resolveBuiltAsset，最终统一输出 export default <url 或 data URL> 形式的模块代码。开发环境下，fileToDevUrl 的处理逻辑非常直白：public 目录内的资源保留原路径；项目根内的资源推导出短公开路径（/ + 相对路径）；项目根外的资源则使用 /@fs/ 前缀的绝对文件系统路径，交由静态中间件特殊处理。

内联判断：shouldInline 的完整决策链

文档提到“小于 assetsInlineLimit 的资源会内联为 base64”，其默认值 4096（4 KiB）定义于 DEFAULT_ASSETS_INLINE_LIMIT。shouldInline 函数 实现了比文档描述更完整的决策顺序：

1. 命中 ?no-inline → 不内联；命中 ?inline → 强制内联；
2. 仅构建阶段的附加检查：配置了 build.lib（库模式）时总是内联；作为 entry 的模块则不内联；
3. 文件是 .html → 不内联；SVG 带 fragment（#）→ 不内联（因为 SVG 片段设计上是用于复用的）；
4. assetsInlineLimit 若为回调函数，可返回布尔值显式控制，返回 undefined 时回落到默认逻辑；
5. 最终条件：content.length < limit 且 内容不是 Git LFS 占位符（isGitLfsPlaceholder 通过比对文件头部 version https://git-lfs.github.com 前缀识别）。

内联为 data URL 时，assetToDataURL 对 SVG 有特殊处理：走 svgToDataURL，若 SVG 含 <text>、<foreignObject> 或嵌套引号则退回 base64 编码，否则输出 URL 编码的 data:image/svg+xml,...（对 "、%、#、<、>、空白逐一转义）——通常比 base64 更小且可读性更好。此外 MIME 类型由 mrmime 查询，registerCustomMime 还针对 .ico/.cur 补上了 image/x-icon 等自定义映射。

小技巧：通过 url() 内联 SVG

当用 JS 手工构造 url() 传入 SVG 的 data URL 时，变量需要包裹在双引号内：

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

原因正对应上文源码中的转义规则：SVG data URL 中内部引号已被替换为单引号，外层再用双引号包裹即可避免 CSS 解析冲突。

显式 URL 导入：?url 后缀

不在内置清单（或 assetsInclude）中的文件，可以用 ?url 后缀显式按 URL 导入。典型场景是导入 Houdini Paint Worklet：

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

在源码中，?url 由 urlRE 正则识别，并在 asset 插件的 resolveId 过滤器 中优先放行。

显式内联控制：?inline 与 ?no-inline

可以显式指定内联或不内联，覆盖 assetsInlineLimit 的默认判断：

import 'vite/client'
import imgUrl1 from './img.svg?no-inline'
import imgUrl2 from './img.png?inline'

对应源码中的 inlineRE / noInlineRE 两个正则。另外值得注意的是，开发环境下 fileToDevUrl 会让“构建中会被内联的 SVG”在开发时也内联，以避免 dev/build 之间因引号处理差异导致的行为不一致。

将资源导入为字符串：?raw 后缀

用 ?raw 后缀可将资源文件内容作为字符串导入：

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

实现位于 asset 插件 load 钩子的 raw 分支：直接从磁盘读取文件（若命中 public 目录则读 public 下的对应文件），以 export default <JSON 字符串> 形式返回，并 addWatchFile 以便 HMR 感知变更。

将脚本导入为 Web Worker

脚本可以用 ?worker 或 ?sharedworker 后缀导入为 Web Worker 构造函数：

import 'vite/client'
// 生产构建中为独立 chunk
import Worker from './shader.js?worker'
const worker = new Worker()

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

import 'vite/client'
// 内联为 base64 字符串
import InlineWorker from './shader.js?worker&inline'

client.d.ts 为 *?worker、*?worker&inline、*?worker&url、*?sharedworker、*?sharedworker&inline、*?sharedworker&url 均提供了类型声明，分别导出 Worker/SharedWorker 构造函数或 string。更完整的 Worker 用法参见 docs/guide/features.md 的 Web Worker 章节。

public 目录

如果某类资源满足以下任一条件，应放入 public 目录：

• 从不会被源代码引用（例如 robots.txt）；
• 必须保留完全相同的文件名（不带哈希）；
• 或者你只是不想为了拿到一个 URL 而先 import 一次资源。

将资源放入项目根目录下的特殊 public 目录后：开发阶段它们以根路径 / 提供服务；构建时原样复制到 dist 目录根部。目录默认为 <root>/public，可通过 publicDir 选项 配置。

注意：引用 public 资源时应始终使用根绝对路径——例如 public/icon.png 在源码中应写作 /icon.png。

选择建议（来自官方文档提示）： 一般优先导入资源，除非你确实需要 public 目录提供的上述保证（保留文件名、免导入）。

源码层面，publicDir.ts 负责这块逻辑：initPublicFiles 在启动时递归扫描 public 目录建立内存集合，checkPublicFile 以 O(1) 方式判断某个以 / 开头的 URL 是否命中 public 文件，并对 ../ 这类越界路径做了防御。构建产物侧，publicFileToBuiltUrl 把 public 资源 URL 编码为 __VITE_PUBLIC_ASSET__<hash>__ 占位符，在 renderAssetUrlInJS 阶段再统一替换为基于 base 的最终路径，从而支持相对 base 部署场景。

new URL(url, import.meta.url) 处理动态相对路径

import.meta.url 是原生 ESM 特性，暴露当前模块的 URL。将它与原生 URL 构造函数组合，即可用相对路径获取静态资源完整 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 不会转换这种写法
const imgUrl = new URL(imagePath, import.meta.url).href

源码视角：转换的具体实现

负责该特性的插件是 assetImportMetaUrl.ts。它通过 assetImportMetaUrlRE 正则匹配 new URL('...', import.meta.url) 形态，并区分两类情况处理：

• 静态字符串：解析出实际文件（./ 开头走文件系统解析，否则走资源解析器；命中 public 目录时转换为公开路径），调用 fileToUrl 得到构建 URL，再改写为 new URL(<构建URL表达式>, '' + import.meta.url)；文件在构建期不存在时保留原始 URL 并给出警告，可用 /* @vite-ignore */ 注释抑制；
• 含 ${} 的模板字符串：解析模板 AST，把插值段映射为 * 构造 glob 模式（例如 `./dir/${name}.png` → ./dir/*.png），然后改写为 new URL((import.meta.glob(pattern, { eager: true, import: 'default', query: '?url' }))[原始模板], import.meta.url)（见 assetImportMetaUrl.ts#L79-L116），即把“运行时查表”转换为“构建期一次性 eager 导入 + 运行时按模板取值”；若模式以 * 开头（相当于匹配所有文件）则不做转换。

说明：早期文档版本中展示的是“显式 import + 对象映射表”的转换示意，当前仓库源码采用的是上面的 import.meta.glob 方案，最终语义等价——构建产物中动态路径集合被静态化。

限制：SSR 下不可用

该模式不适用于 SSR 场景，因为 import.meta.url 在浏览器与 Node.js 中语义不同，且服务端包无法预先确定客户端的主机 URL。插件的 applyToEnvironment（assetImportMetaUrl.ts#L53-L55）也印证了这一点：仅对 consumer === 'client' 的环境生效。

小结

Vite 的静态资源处理围绕三条主线：import 即 URL（内置类型自动识别 + assetsInclude 扩展）、查询后缀显式控制（?url、?inline、?no-inline、?raw、?worker）、public 目录承载免导入资源。配合 assetsInlineLimit（默认 4096 字节）的内联策略与构建期对 new URL(..., import.meta.url) 的静态化转换，覆盖了从开发到生产部署（含相对 base、Git LFS、SVG 特殊编码）的完整链路。相关配置项详见 assetsInclude、build.assetsInlineLimit 与 publicDir；核心实现可进一步参阅 vite:asset 插件 与 vite:asset-import-meta-url 插件。