Solucionar problemas em aplicativos Node.js no Azure Functions

Importante

O conteúdo deste artigo é alterado com base na escolha do modelo de programação Node.js no seletor na parte superior da página. O modelo v4 normalmente está disponível e foi projetado para oferecer uma experiência mais flexível e intuitiva para desenvolvedores de JavaScript e TypeScript. Confira o guia de migração para conhecer as diferenças entre a v3 e a v4.

Este artigo fornece um guia para solucionar problemas de cenários comuns em aplicativos de funções Node.js.

A guia Diagnosticar e resolver problemas no portal Azure é um recurso útil para monitorar e diagnosticar possíveis problemas relacionados ao seu aplicativo. Ele também fornece soluções potenciais para seus problemas com base no diagnóstico. Para obter mais informações, consulte Diagnósticos do aplicativo de funções do Azure.

Outro recurso útil é a guia Logs no portal Azure para sua instância do Application Insights para que você possa executar consultas KQL personalizadas. A consulta de exemplo a seguir mostra como exibir erros e avisos para seu aplicativo no último dia:

let myAppName = "<your app name>";
let startTime = ago(1d);
let endTime = now();
union traces,requests,exceptions
| where cloud_RoleName =~ myAppName
| where timestamp between (startTime .. endTime)
| where severityLevel > 2

Se esses recursos não resolverem seu problema, as seções a seguir fornecerão conselhos para problemas específicos do aplicativo:

Nenhuma função encontrada

Se você vir qualquer um dos seguintes erros em seus logs:

Nenhum gatilho HTTP encontrado.

Nenhuma função de trabalho encontrada. Tente tornar suas classes de trabalho e métodos públicos. Se você estiver usando extensões de associação (por exemplo, Armazenamento do Azure, ServiceBus, Timers etc.) certifique-se de ter chamado o método de registro para as extensões em seu código de inicialização (por exemplo, construtor. AddAzureStorage(), construtor. AddServiceBus(), construtor. AddTimers(), etc.).

Experimente as seguintes correções:

  • Ao executar localmente, verifique se você está usando Azure Functions Core Tools v4.0.5382 ou superior.
  • Ao executar em Azure:

    • Verifique se você está usando Azure Functions Runtime versão 4.25 ou superior.

    • Verifique se você está usando Node.js v18 ou superior.

    • Defina a configuração FUNCTIONS_NODE_BLOCK_ON_ENTRY_POINT_ERROR do aplicativo como true. Essa configuração é recomendada para todos os aplicativos do modelo v4 e garante que todos os erros de ponto de entrada estejam visíveis nos logs de insights do aplicativo. Para obter mais informações, veja Referência das configurações de aplicativos para o Azure Functions.

    • Verifique os logs do Aplicativo de Funções para identificar erros no ponto de entrada. A consulta de exemplo a seguir mostra como visualizar erros no ponto de entrada do seu aplicativo no último dia:

      let myAppName = "<your app name>";
let startTime = ago(1d);
let endTime = now();
union traces,requests,exceptions
| where cloud_RoleName =~ myAppName
| where timestamp between (startTime .. endTime)
| where severityLevel > 2
| where message has "entry point"
  • Verifique se o aplicativo tem a estrutura de pastas necessária com um host.json na raiz e uma pasta para cada função que contém um arquivo function.json .

A solicitação Undici não é um construtor

Se você receber o seguinte erro nos logs do aplicativo de funções:

System.Private.CoreLib: exceção durante a execução da função: Functions.httpTrigger1. System.Private.CoreLib: Resultado: exceção de falha: undici_1.Request não é um construtor

Verifique se você está usando Node.js versão 22.x ou superior.

Falha ao detectar o runtime do Azure Functions

Se você receber o seguinte erro nos logs do aplicativo de funções:

AVISO: Falha ao detectar o runtime do Azure Functions. Alternando o pacote "@azure/functions" para o modo de teste - nem todos os recursos têm suporte.

Verifique se o arquivo package.json faz referência a applicationinsights e confirme se a versão é ^2.7.1 ou posterior. Depois de atualizar a versão, execute npm install

Streams HTTP não funcionam

Se o streaming HTTP não estiver funcionando:

  • Verifique @azure/functions se a versão do pacote é 4.3.0 ou posterior.
  • Certifique-se de que a versão de runtime do Azure Functions seja 4.28 ou posterior.
  • Verifique se app.setup({ enableHttpStream: true }) é chamado.
  • O Verify FUNCTIONS_REQUEST_BODY_SIZE_LIMIT está configurado adequadamente para grandes volumes de dados.

Ganchos não executando

Se seus ganchos não estiverem funcionando:

  • Confirme se você está usando o modelo de programação v4.
  • Verifique a sintaxe do registro de ganchos: app.hook.preInvocation() ou app.hook.appStart().
  • Verifique se você registra os hooks antes das definições de funções.
  • Revise o filtro de gatilhos se os hooks devem ser executados apenas para tipos específicos de funções.

Problemas de compilação do TypeScript

Para problemas específicos do TypeScript:

Falhas na montagem:

  • O Verify tsconfig.json tem o apontamento correto outDir para a saída da sua compilação
  • Garanta que, no modelo v3, scriptFile aponte para arquivos .js compilados, não .ts
  • Verifique se todas as dependências do TypeScript estão instaladas: npm install --save-dev typescript @types/node

Erros de tipo:

  • Pacote de atualização @azure/functions para definições de tipos mais recentes
  • Use importações corretas: import { app, HttpRequest, InvocationContext } from '@azure/functions'
  • Verifique se as assinaturas de funções correspondem aos tipos esperados

Problemas de resolução de módulos

Não é possível encontrar erros de módulo:

  • Execute npm install para garantir que todas as dependências estejam instaladas
  • A pasta Check node_modules existe no pacote de implantação
  • Para módulos ES, certifique-se de que os nomes dos arquivos usem .mjs extensão ou package.json tenha "type": "module"
  • Verifique se os caminhos de importação relativos estão corretos após a compilação do TypeScript

Questões de ambiente e configuração

Variáveis de ambiente ausentes:

  • Adicionar variáveis a local.settings.json para desenvolvimento local
  • Defina as Configurações de Aplicação no portal do Azure para implantação na nuvem
  • Uso process.env["VARIABLE_NAME"] para acessar valores

Problemas de registro:

  • Use context.log() em vez de console.log() para logs específicos de função
  • Verifique se a cadeia de conexão do Application Insights está configurada
  • Verifique os níveis de log para filtragem em host.json

Obter ajuda do Microsoft

Você pode obter mais ajuda do Microsoft de uma das seguintes maneiras:

  • Pesquise os problemas conhecidos no repositório Azure Functions Node.js. Se você não encontrar seu problema listado, crie um novo problema e informe-nos o que aconteceu.
  • Se você não conseguir diagnosticar seu problema usando este guia, Microsoft engenheiros de suporte estarão disponíveis para ajudar a diagnosticar problemas com seu aplicativo. Microsoft oferece vários planos de suporte. Crie um tíquete de suporte na seção Suporte + solução de problemas da página do aplicativo de funções no portal do Azure.

Próximas Etapas 

  • Last updated on