Alcance del protocolo de activos

Tauri puede servir archivos desde el disco hacia el WebView a través del protocolo personalizado asset (por ejemplo, cuando usas convertFileSrc en el frontend). Si una ruta está permitida o no, lo controla app.security.assetProtocol en tauri.conf.json.

Debes establecer enable en true y definir un scope que enumere qué rutas del sistema de archivos se pueden exponer. Las rutas resueltas en tiempo de ejecución deben coincidir con ese alcance, o el WebView se negará a cargar (a menudo con un error como “protocolo de activos no configurado para permitir la ruta”).

La Política de Seguridad de Contenido para fuentes asset: está documentada en la página Política de Seguridad de Contenido (CSP). Esta página se centra en el alcance y cómo interactúa con los globs y los segmentos de rutas ocultas.

Cómo se define el alcance

assetProtocol.scope utiliza el mismo tipo FsScope que la configuración relacionada con el sistema de archivos en otros lugares: ya sea un array JSON de patrones glob permitidos, o un objeto JSON con allow, deny opcional y requireLiteralLeadingDot opcional. Para saber cómo se integran los “alcances” en el modelo de seguridad de Tauri de forma más amplia, consulta Alcances de comandos.

Los patrones pueden comenzar con una variable de directorio base (por ejemplo, $HOME, $CACHE, $APPCACHE, $APPDATA, $RESOURCE). Consulta las APIs de ruta / directorio base para ver el conjunto completo de variables en las que puede confiar tu aplicación.

Las rutas resueltas al cargar activos suelen ser absolutas (en Linux, a menudo bajo /home/...). Un patrón como ["*/**"] típicamente no coincide con esas rutas, porque no se alinea con una barra inicial / o una variable de directorio base. Prefiere patrones como $HOME/**/*, /home/usuario/**/* u otra forma que refleje la ruta resuelta.

Forma de array (solo rutas permitidas)

Usa una lista cuando solo necesites una lista permitida fija y el comportamiento por defecto de glob sea suficiente:

src-tauri/tauri.conf.json

{
  "app": {
    "security": {
      "assetProtocol": {
        "enable": true,
        "scope": ["$APPCACHE/**/*", "$RESOURCE/**/*"]
      }
    }
  }
}

Con la forma de array no puedes establecer requireLiteralLeadingDot; para eso, usa la forma de objeto a continuación.

Forma de objeto (allow, deny, requireLiteralLeadingDot)

Usa un objeto cuando necesites reglas de deny o para cambiar la coincidencia del punto inicial:

src-tauri/tauri.conf.json

{
  "app": {
    "security": {
      "assetProtocol": {
        "enable": true,
        "scope": {
          "allow": ["$APPCACHE/**/*"],
          "deny": ["$APPCACHE/**/secrets/**"]
        }
      }
    }
  }
}

deny tiene prioridad sobre allow cuando ambos coinciden.

Unix: segmentos de ruta que comienzan con .

En Unix, requireLiteralLeadingDot tiene como valor predeterminado true. Entonces los tokens de comodín como *, ?, ** y [...] no coinciden con un componente de ruta que comience con . (archivos punto y directorios punto como .cache o .ssh).

Así que un patrón como $HOME/** puede permitir /home/user/Documents/file.png pero no /home/user/.cache/myapp/preview.png, porque .cache es un componente con prefijo de punto. Un patrón que nombra el segmento literalmente (por ejemplo $HOME/.cache/myapp/**) sí coincide.

Para permitir componentes con prefijo de punto bajo un glob amplio, puedes establecer requireLiteralLeadingDot en false en el alcance del objeto (esto amplía lo que puede cargar el WebView; revisa con cuidado):

src-tauri/tauri.conf.json

{
  "app": {
    "security": {
      "assetProtocol": {
        "enable": true,
        "scope": {
          "requireLiteralLeadingDot": false,
          "allow": ["$HOME/**/*"]
        }
      }
    }
  }
}

¿Sigue bloqueado en rutas al estilo Linux?

Los miembros de la comunidad a menudo se topan con esto cuando una ruta pasa a través de un directorio punto (por ejemplo ~/.cache/...) mientras que el patrón permitido solo usa ** bajo $HOME. Consulta la discusión en tauri#13788 para ver ejemplos concretos y soluciones.

Prefiere **/* sobre ** a secas para “todos los archivos bajo este directorio”

Para patrones glob que deban coincidir con archivos en un árbol, prefiere **/* (y variantes como $DIR/**/*) en lugar de ** a secas, en consonancia con otros ejemplos de rutas de Tauri. Es fácil hacer un mal uso de ** a secas cuando tu intención es “todo lo que esté bajo este directorio de forma recursiva”.

Configuración altamente permisiva (usar con extremo cuidado)

Si intencionalmente necesitas el acceso más amplio posible y segmentos con prefijo de punto, una forma sugerida por los mantenedores se ve así. Esta no es una recomendación por defecto; aumenta la exposición de archivos ocultos y sensibles.

src-tauri/tauri.conf.json

{
  "app": {
    "security": {
      "assetProtocol": {
        "enable": true,
        "scope": {
          "requireLiteralLeadingDot": false,
          "allow": ["**/*"]
        }
      }
    }
  }
}

Precaución

Prefiere directorios estrechos ($APPCACHE, $RESOURCE, una sola subcarpeta de la aplicación bajo $HOME, etc.) en lugar de patrones amplios como $HOME/**/* o **/* a menos que tengas una razón poderosa y comprendas los compromisos de seguridad.

Configuración estática vs rutas elegidas dinámicamente

Las entradas en tauri.conf.json describen patrones de permitir/denegar estáticos. No reemplazan los flujos de trabajo en tiempo de ejecución donde el usuario elige carpetas o archivos arbitrarios (por ejemplo con el plugin dialog): esas rutas pueden requerir ser persistidas entre reinicios usando el plugin persisted-scope.

Para persistir el alcance relacionado con asset / protocolo con ese plugin, habilita su función de Cargo protocol-asset en src-tauri/Cargo.toml, por ejemplo:

tauri-plugin-persisted-scope = { version = "2", features = ["protocol-asset"] }

Registra tauri_plugin_fs antes de tauri_plugin_persisted_scope como se describe en la guía del plugin.

Solución de problemas

Síntoma	Cosas a verificar
“protocolo de activos no configurado para permitir la ruta”	La ruta debe coincidir con un patrón allow; deny anula a allow. Usa patrones absolutos o variables del estilo $VAR/$HOME que coincidan con la forma en que se resuelve la ruta en el disco.
Funciona para carpetas normales pero no bajo .cache / .config	En Unix, el comportamiento predeterminado de requireLiteralLeadingDot: usa un .segmento literal en el patrón, o establece requireLiteralLeadingDot: false en el alcance del objeto (consulta tauri#13788).
El usuario eligió una carpeta en tiempo de ejecución; sigue bloqueado tras reiniciar	Es posible que necesites persisted-scope con la función protocol-asset, no solo entradas en tauri.conf.json.
Un ** amplio parece incorrecto	Prueba **/* para globs orientados a archivos; consulta Empaquetado de archivos adicionales para obtener orientación similar sobre ** vs **/* en recursos de bundles.
Un alcance como ["*/**"] nunca coincide en Linux	Las rutas resueltas son absolutas; usa variables $..., una barra / inicial u otro patrón que coincida con la ruta real (ver arriba).

Los tipos de Rust definitivos para assetProtocol y FsScope residen en config.rs de Tauri (AssetProtocolConfig, FsScope). La referencia de configuración generada puede procesar los campos anidados de FsScope de forma compacta o difícil de leer; si algo no parece claro allí, verifica con esta página y la sección requireLiteralLeadingDot del plugin del sistema de archivos (la configuración del plugin usa el mismo nombre de opción para sus propios alcances). Si la referencia aún no documenta claramente esos campos, considera abrir un issue en el repositorio tauri-docs para que el generador de configuración pueda mejorarse.