前端工程化 / 系统课时

管理静态资源导入

管理静态资源导入

本课建立一套可预测的静态资源规则:源码中的资源进入构建图并可能改名,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 静态资源从源码到开发地址与构建产物的路径

用一个页面观察不同结果

在标准 Vite 项目中准备 src/assets/logo.svg、src/assets/manual.pdf、src/assets/icon.svg、src/assets/note.txt,并把另一个图标放到 public/favicon.svg。下面代码会把每种导入结果直接显示到页面,便于比较。

js
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>
`

预期结果

text
页面显示“资源导入检查”:
- 开发环境中的源码图片和 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 仍会要求输出文件。

ts
import { defineConfig } from 'vite'

export default defineConfig({
  build: {
    assetsInlineLimit: 0,
  },
})

生效行为与验证方法:重新构建后,普通源码资源会作为独立文件输出;检查 dist/assets 中的文件名,并确认页面仍通过导入得到的最终 URL 正常加载。

bash
npm run build

预期输出

text
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 管理候选文件。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

管理静态资源导入

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通