前端工程化 / 系统课时
管理静态资源导入
管理静态资源导入
本课建立一套可预测的静态资源规则:源码中的资源进入构建图并可能改名,public 文件保持原名,查询后缀决定按 URL、字符串或内联数据读取。完成后,你能在开发与生产环境中准确判断资源地址。
学习目标
- 区分源码导入与
public目录的适用边界 - 使用
?url、?inline、?no-inline和?raw控制加载方式 - 通过构建产物验证哈希、内联和根路径引用
选择资源进入项目的方式
源码导入适合被组件直接引用、需要哈希命名、依赖追踪或插件处理的资源。public 目录适合必须保留原始文件名、不会从源码导入,或需要固定根路径访问的文件,例如 robots.txt。
| 写法 | JavaScript 得到的值 | 生产构建行为 |
|---|---|---|
import logo from './logo.svg' |
解析后的 URL | 进入资源图,可能哈希或内联 |
import fileUrl from './manual.pdf?url' |
明确按 URL 读取 | 按资源规则输出文件或内联 |
import icon from './icon.svg?inline' |
data: URL |
强制内联 |
import icon from './icon.svg?no-inline' |
文件 URL | 强制输出文件 |
import text from './note.txt?raw' |
文件文本内容 | 作为字符串打进模块 |
/favicon.svg |
根路径 URL | 从 public 原样复制到输出根目录 |

用一个页面观察不同结果
在标准 Vite 项目中准备 src/assets/logo.svg、src/assets/manual.pdf、src/assets/icon.svg、src/assets/note.txt,并把另一个图标放到 public/favicon.svg。下面代码会把每种导入结果直接显示到页面,便于比较。
import logoUrl from './assets/logo.svg'
import manualUrl from './assets/manual.pdf?url'
import inlineIconUrl from './assets/icon.svg?inline'
import noteText from './assets/note.txt?raw'
const publicIconUrl = '/favicon.svg'
document.querySelector('#app').innerHTML = `
<h1>资源导入检查</h1>
<ul>
<li>源码图片:<code>${logoUrl}</code></li>
<li>URL 查询:<code>${manualUrl}</code></li>
<li>强制内联:<code>${inlineIconUrl.slice(0, 32)}...</code></li>
<li>public 文件:<code>${publicIconUrl}</code></li>
</ul>
<pre>${noteText}</pre>
`预期结果
页面显示“资源导入检查”:
- 开发环境中的源码图片和 PDF 显示可访问的开发 URL
- 强制内联项以 data: 开头
- public 文件始终显示 /favicon.svg
- note.txt 的内容作为普通文本显示普通导入和 ?url 都返回 URL,但前者依赖 Vite 的资源类型识别,后者明确要求按 URL 处理。?raw 返回内容本身,不应再把结果赋给图片或下载链接。
预测开发与构建后的地址
开发环境强调快速服务,源码资源通常保留可定位的开发 URL。生产构建会把被引用资源纳入资源图:超过内联阈值或使用 ?no-inline 的文件通常输出到构建资源目录,并获得内容哈希;较小资源可能转成 data: URL。
public/favicon.svg 不参与哈希和插件转换。无论源码文件位于 public 的哪一级,引用时都从根路径开始,例如文件 public/docs/help.pdf 应写成 /docs/help.pdf,而不是 /public/docs/help.pdf。
当项目部署在非根路径时,不要在业务代码中随意拼接构建后的哈希文件名。优先使用导入返回的 URL;需要组合公共基础路径时,使用 Vite 提供的环境信息或项目统一的路径函数。
控制自动内联边界
build.assetsInlineLimit 控制普通导入资源是否自动内联。下面配置关闭自动内联,便于在网络面板和构建目录中观察每个文件;显式的 ?inline 仍会要求内联,?no-inline 仍会要求输出文件。
import { defineConfig } from 'vite'
export default defineConfig({
build: {
assetsInlineLimit: 0,
},
})生效行为与验证方法:重新构建后,普通源码资源会作为独立文件输出;检查 dist/assets 中的文件名,并确认页面仍通过导入得到的最终 URL 正常加载。
npm run build预期输出
vite v<VERSION> building for production...
dist/index.html <SIZE>
dist/assets/logo-<HASH>.svg <SIZE>
dist/assets/manual-<HASH>.pdf <SIZE>
✓ built in <TIME>实际文件名、数量、大小和构建耗时会因资源内容与 Vite 版本不同而变化。若 icon.svg?inline 没出现在目录中是正常现象,因为它已进入 JavaScript 产物。
避免地址相关的常见错误
不要从源码中写死 /assets/logo-<HASH>.svg,哈希会随内容变化。不要把 public 文件写成相对当前模块的 ./public/file,也不要期待 public 文件被压缩、改名或树摇。
动态资源路径需要让 Vite 在构建时可分析。静态相对路径可使用 new URL('./assets/logo.svg', import.meta.url).href;完全由运行时变量拼出的未知路径可能无法转换,此时应改用显式映射或 import.meta.glob 管理候选文件。