Manipulação de Recurso Estático

• Relacionado com: Caminho de Base Pública
• Relacionado com: opção de configuração assetsInclude

Importando o Recurso como URL

A importação dum recurso estático retornará a URL pública resolvida quando esta for servida:

import 'vite/client'

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

Por exemplo, a imgUrl será /img.png durante o desenvolvimento, e torna-se-á /assets/img.2d8efhg.png na construção de produção.

O comportamento é semelhante ao file-loader da Webpack. A diferença é que a importação pode estar ou usando os caminhos públicos absolutos (baseado na raiz do projeto durante desenvolvimento) ou caminhos relativos.

• As referências de url() na CSS são tratadas da mesma maneira.

• Se usamos a extensão de Vue, as referências de recurso nos modelos de marcação dos componentes de ficheiro único da Vue são convertidos automaticamente em importações.

• Os tipos de ficheiro de imagem, media, e fonte comuns são detetados como recursos automaticamente. Nós podemos estender a lista interna usando a opção assetsInclude.

• Os recursos referenciados são incluídos como parte do gráfico de recursos de construção, terão os nomes de ficheiro baralhados com caracteres pseudo-aleatório, e poderão ser processados por extensões para otimização.

• Os recursos mais pequenos em bytes do que a opção assetsInlineLimit serão embutidos como URLs de dados de base64.

• Os reservadores de espaço do armazenamento de ficheiros grandes da Git são excluídos automaticamente da incorporação porque não contêm o conteúdo do ficheiro que representam. Para obter a incorporação, devemos certificar-nos de descarregar o conteúdo do ficheiro através do armazenamento de ficheiro grandes da Git antes da construção.

• A TypeScript, por padrão, não reconhece as importações de recurso estático como módulos válidos. Para corrigir isto, incluímos vite/client.

Incorporação de SVGs através da url()

Quando passamos um localizador uniforme de recursos de gráficos vetoriais escaláveis a uma url() construída manualmente por JavaScript, a variável deve ser envolvida entre aspas duplas.

import 'vite/client'

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

Importações de URL Explicita

Os recursos que não estão incluídos na lista interna ou na assetsInclude, podem ser explicitamente importados como uma URL usando o sufixo ?url. Isto é útil, para por exemplo, importar os Painéis de Trabalho de Pintura da Houdini:

import 'vite/client'

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

Importando Recurso como Sequência de Caracteres

Os recursos podem ser importados como sequências de caracteres usando o sufixo ?raw:

import 'vite/client'

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

Importando Programa como um Operário

Os programas podem ser importados como operários da Web com o sufixo ?worker ou ?sharedworker:

import 'vite/client'

// Separar pedaço na construção de produção
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'

// Embutido como sequências de caracteres de base64
import InlineWorker from './shader.js?worker&inline'

Consultar a secção de Operário da Web por mais detalhes.

O Diretório public

Se tivermos recursos que:

• Nunca são referenciados no código-fonte (como por exemplo, robots.txt)
• Devem reter o mesmo exato nome de ficheiro (sem os embaralhar com caracteres pseudo-aleatórios)
• ...ou simplesmente não queremos ter de primeiro importar um recurso para apenas obter a sua URL

Então podemos colocar o recurso num diretório public especial sob a raiz do nosso projeto. Os recursos neste diretório serão servidos no caminho de raiz / durante o desenvolvimento, e copiados para a raiz do diretório de distribuição (abreviado como dist) como está.

O diretório é predefinido para <root>/public, mas pode ser configurado através da opção publicDir.

Nota que sempre devemos referenciar os recursos do diretório public usando o caminho absoluto da raiz - por exemplo, public/icon.png deve ser referenciado no código-fonte como /icon.png.

new URL(url, import.meta.url)

import.meta.url é uma funcionalidade do módulo de ECMAScript nativo que expõe a URL do módulo atual. Combinando-o com o construtor de URL nativo, podemos obter a URL completa resolvida dum recurso estático usando caminho relativo a partir dum módulo de JavaScript:

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

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

Isto funciona de maneira nativa nos navegadores modernos - de fato, a Vite não precisa processar este código durante o desenvolvimento!

Este padrão suporta URLs dinâmicas através dos literais de modelo:

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

Durante a construção de produção, a Vite realizará as transformações necessárias para que as URLs continuem a apontar para a localização correta mesmo depois do empacotamento e embaralhação do recurso com caracteres pseudo-aleatórios. No entanto, a sequência de caracteres da URL deve ser estática para poder ser analisada, de outro modo o código será deixado como está, o que pode causar erros de execução se build.target não suportar import.meta.url:

// A Vite não transformará isto
const imgUrl = new URL(imagePath, import.meta.url).href

NÃO FUNCIONA COM A INTERPRETAÇÃO DO LADO DO SERVIDOR

Este padrão não funciona se estivermos usando a Vite para interpretação do lado do servidor, porque import.meta.url tem semânticas diferentes nos navegadores versus a Node.js. O pacote do servidor também não pode determinar antecipadamente a URL do hospedeiro do cliente.