Umgang mit statischen Assets

• Verwandt: Öffentlicher Basispfad
• Verwandt: assetsInclude-Konfigurationsoption

Importieren von Assets als URL

Das Importieren eines statischen Assets gibt die aufgelöste öffentliche URL zurück, wenn es bereitgestellt wird:

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

Beispielsweise ist imgUrl während der Entwicklung /img.png und wird im Produktionsbuild zu /assets/img.2d8efhg.png.

Das Verhalten ähnelt dem von webpack's file-loader. Der Unterschied besteht darin, dass der Import entweder absolute öffentliche Pfade (basierend auf dem Projektstamm während der Entwicklung) oder relative Pfade verwenden kann.

• url()-Verweise in CSS werden auf die gleiche Weise behandelt.

• Wenn das Vue-Plugin verwendet wird, werden Asset-Verweise in Vue-SFC-Vorlagen automatisch in Imports umgewandelt.

• Häufig verwendete Bild-, Medien- und Schriftdateiformate werden automatisch als Assets erkannt. Sie können die interne Liste mithilfe der assetsInclude-Option erweitern.

• Referenzierte Assets werden als Teil des Build-Asset-Graphen einbezogen, erhalten gehashte Dateinamen und können von Plugins zur Optimierung verarbeitet werden.

• Assets, die weniger Bytes als die assetsInlineLimit-Option haben, werden als Base64-Daten-URLs inline eingefügt.

• Git LFS-Platzhalter werden automatisch vom Inline-Ausschluss ausgenommen, da sie den Inhalt der von ihnen repräsentierten Datei nicht enthalten. Um das Inline-Einfügen zu ermöglichen, stellen Sie sicher, dass Sie die Dateiinhalte über Git LFS vor dem Build herunterladen.

• TypeScript erkennt statische Asset-Importe standardmäßig nicht als gültige Module. Um dies zu beheben, schließen Sie vite/client ein.

Einbindung von SVGs durch url()

Bei der Übergabe einer SVG-URL an eine manuell erstellte url() durch JS sollte die Variable in Anführungszeichen gesetzt werden.

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

Explizite URL-Imports

Assets, die nicht in der internen Liste oder in assetsInclude enthalten sind, können explizit als URL mit dem Suffix ?url importiert werden. Dies ist nützlich, um beispielsweise Houdini Paint Worklets zu importieren.

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

Importieren von Assets als Zeichenfolge

Assets können als Zeichenfolgen mithilfe des Suffix ?raw importiert werden.

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

Importieren von Skripten als Worker

Skripte können als Web Worker mit dem Suffix ?worker oder ?sharedworker importiert werden.

// Separater Chunk im Produktionsbuild
import Worker from './shader.js?worker'
const worker = new Worker()

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

// Als Base64-Zeichenfolgen eingebettet
import InlineWorker from './shader.js?worker&inline'

Weitere Details finden Sie im Web Worker-Abschnitt.

Das public-Verzeichnis

Wenn Sie Assets haben, die:

• Im Quellcode nie referenziert werden (z. B. robots.txt)
• Den exakt gleichen Dateinamen behalten müssen (ohne Hashing)
• ...oder wenn Sie einfach nicht möchten, dass Sie zuerst ein Asset importieren müssen, um seine URL zu erhalten

Dann können Sie das Asset in einem speziellen public-Verzeichnis unter Ihrem Projektstamm platzieren. Assets in diesem Verzeichnis werden während der Entwicklung unter dem Pfad / bereitgestellt und im Verzeichnis dist unverändert im Stammverzeichnis kopiert.

Das Verzeichnis wird standardmäßig zu <Projektstamm>/public festgelegt, kann jedoch über die publicDir-Option konfiguriert werden.

Beachten Sie, dass:

• Sie public-Assets immer mit absolutem Wurzelpfad referenzieren sollten. Zum Beispiel sollte public/icon.png im Quellcode als /icon.png referenziert werden.
• Assets in public können nicht aus JavaScript importiert werden.

new URL(url, import.meta.url)

import.meta.url ist ein natives ESM-Feature, das die URL des aktuellen Moduls offenlegt. Indem es mit dem nativen URL-Konstruktor kombiniert wird, können wir die vollständige, aufgelöste URL eines statischen Assets mithilfe eines relativen Pfads aus einem JavaScript-Modul erhalten:

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

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

Dies funktioniert nativ in modernen Browsern - tatsächlich muss Vite diesen Code während der Entwicklung überhaupt nicht verarbeiten!

Dieses Muster unterstützt auch dynamische URLs über Vorlagenliterale:

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

Während des Produktionsbuilds führt Vite die erforderlichen Transformationen durch, damit die URLs auch nach Bündelung und Asset-Hashing weiterhin auf den richtigen Speicherort zeigen. Die URL-Zeichenfolge muss jedoch statisch sein, damit sie analysiert werden kann, andernfalls bleibt der Code unverändert, was zu Laufzeitfehlern führen kann, wenn build.target import.meta.url nicht unterstützt.

// Vite wird dies nicht transformieren
const imgUrl = new URL(imagePath, import.meta.url).href

Funktioniert nicht mit SSR

Dieses Muster funktioniert nicht, wenn Sie Vite für Server-seitiges Rendern verwenden, da import.meta.url unterschiedliche Semantiken in Browsern gegenüber Node.js hat. Das Server-Bundle kann auch die Client-Host-URL im Voraus nicht ermitteln.