WebGPU: dicas de solução de problemas e correções

François Beaufort
François Beaufort
GitHub

Publicado em: 7 de fevereiro de 2024, Última atualização: 17 de outubro de 2025

Este documento explica por que a WebGPU pode estar inoperante ou não funcionar como esperado no navegador Chrome, com etapas claras para resolver os problemas, quando possível.

O exemplo a seguir mostra um erro de JavaScript que pode aparecer quando gpu não está disponível em navigator:

const adapter = await navigator.gpu.requestAdapter();

cancel Uncaught TypeError: Cannot read properties of undefined (reading 'requestAdapter')

Isso pode acontecer por um dos seguintes motivos: Confira nesta ordem específica:

  1. O WebGPU exige o Chrome 113 ou mais recente no ChromeOS, macOS e Windows, e o Chrome 121 ou mais recente no Android. Verifique sua versão em chrome://version e atualize se necessário.

  2. A WebGPU só pode ser acessada em contextos seguros. Se você veicular seu código em um protocolo não seguro (por exemplo, http:, file:), use o protocolo seguro https: ou resolva isso durante o desenvolvimento do seu web app de uma das seguintes maneiras:

    • Execute seu código localmente em http://localhost ou http://127.0.0.1 com um destes comandos: npx http-server ou python3 -m http.server.

    • Adicione a origem à lista "Origens não seguras tratadas como seguras" de chrome://flags/#unsafely-treat-insecure-origin-as-secure e reinicie o Chrome.

    • Instale o Node.js e execute npx servez --ssl para disponibilizar sua pasta por https com um certificado falso. Você ainda vai receber um aviso no Chrome que pode ser ignorado clicando em "Avançado" e "Continuar para...".

    • Exponha seu servidor da Web local à Internet com o ngrok.

O adaptador de GPU é nulo

Confira a seguir um exemplo de erro de JavaScript que pode aparecer quando o adaptador recebido ao chamar requestAdapter() é nulo:

const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();

cancel Uncaught TypeError: Cannot read properties of undefined (reading requestDevice)

Isso acontece por um dos seguintes motivos: Confira nesta ordem específica:

  1. O WebGPU é desativado quando o usuário desativa a opção "Usar aceleração gráfica quando disponível" em chrome://settings/system. Verifique se essa configuração está desativada e ative-a novamente

  2. Ainda não há suporte para WebGPU nesta plataforma. Ative a flag chrome://flags/#enable-unsafe-webgpu e reinicie o Chrome. Para o suporte experimental do Linux, também é necessário ativar a flag chrome://flags/#enable-vulkan. Confira Suporte ao WebGPU no Chrome sem interface gráfica para saber mais.

  3. O hardware da GPU foi adicionado a uma lista de bloqueio específica. Se você encontrar a mensagem "O WebGPU foi desativado por uma lista de bloqueio ou pela linha de comando" em chrome://gpu, desative a lista de bloqueio de adaptadores do WebGPU ativando a flag chrome://flags/#enable-unsafe-webgpu e reiniciando o Chrome. Você também pode substituir a lista de renderização de software integrada ativando a flag chrome://flags/#ignore-gpu-blocklist e reiniciando o Chrome.

  4. Não há um adaptador de GPU correspondente para as opções transmitidas em requestAdapter(). Tente ligar para requestAdapter() com opções diferentes.

  5. O WebGPU requer uma GPU (hardware ou emulada por software). Para verificar se o Chrome detecta uma GPU, acesse chrome://gpu.

  6. O processo da GPU falhou várias vezes. Atualize a página ou reinicie o Chrome. Confira as práticas recomendadas de perda de dispositivo WebGPU para saber mais.

O WebGPU é mais lento que o WebGL

  1. Abra chrome://gpu e confira se você consegue ler "WebGPU: Hardware accelerated". Se você ler "WebGPU: somente software, aceleração de hardware indisponível", talvez seja necessário atualizar os drivers da GPU.

  2. Traduzir diretamente os conceitos do WebGL para o WebGPU pode não aproveitar ao máximo as otimizações exclusivas do WebGPU. Confira Do WebGL ao WebGPU para saber mais sobre algumas das diferenças.

Limitações específicas do Windows

Conheça as seguintes limitações ao usar a WebGPU em dispositivos Windows:

  • O Chrome não é compatível com o uso de vários adaptadores de GPU simultaneamente. Consulte issue chromium:329211593.

  • O Chrome sempre usa o mesmo adaptador de GPU alocado para outras cargas de trabalho do Chrome, que geralmente é a placa gráfica integrada em notebooks devido ao consumo de energia (ou seja, economia de energia). Isso significa que a opção powerPreference não tem impacto ao chamar requestAdapter(). É possível forçar o uso da GPU de alto desempenho, se disponível, ativando a flag chrome://flags/#force-high-performance-gpu e reiniciando o Chrome.