Important
이 문서의 내용은 페이지 상단의 선택기에서 선택한 Node.js 프로그래밍 모델에 따라 변경됩니다. v4 모델은 일반적으로 사용 가능하며 JavaScript 및 TypeScript 개발자를 위해 보다 유연하고 직관적인 환경을 제공하도록 설계되었습니다. 마이그레이션 가이드에서 v3과 v4의 차이점에 대해 자세히 알아봅니다.
이 문서에서는 Node.js 함수 앱의 일반적인 시나리오 문제를 해결하기 위한 가이드를 제공합니다.
Azure 포털의 문제 진단 및 해결 탭은 애플리케이션과 관련된 가능한 문제를 모니터링하고 진단하는 데 유용한 리소스입니다. 또한 진단에 따라 문제에 대한 잠재적 솔루션을 제공합니다. 자세한 내용은 Azure 함수 앱 진단 참조하세요.
또 다른 유용한 리소스는 사용자 지정 KQL 쿼리를 실행할 수 있도록 Application Insights 인스턴스에 대한 Azure 포털의 로그 탭입니다. 다음 예제 쿼리는 지난 날 앱에 대한 오류 및 경고를 보는 방법을 보여 줍니다.
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
이러한 리소스가 문제를 해결하지 못한 경우 다음 섹션에서는 특정 애플리케이션 문제에 대한 조언을 제공합니다.
함수를 찾을 수 없음
로그에 다음 오류가 표시되는 경우:
HTTP 트리거를 찾을 수 없습니다.
작업 함수를 찾을 수 없습니다. 작업 클래스 및 메서드를 공개로 만들어 보세요. 바인딩 확장(예: Azure Storage, ServiceBus, 타이머 등)을 사용하는 경우 시작 코드(예: 작성기)에서 확장에 대한 등록 메서드를 호출했는지 확인합니다. AddAzureStorage(), 작성기. AddServiceBus(), 작성기. AddTimers() 등.
다음 수정 사항을 시도해 보세요.
- 로컬로 실행하는 경우 Azure Functions Core Tools v4.0.5382 이상을 사용하고 있는지 확인합니다.
- Azure 실행하는 경우:
Azure Functions 런타임 버전 4.25 이상을 사용하고 있는지 확인합니다.
Node.js v18 이상을 사용하고 있는지 확인합니다.
앱 설정
FUNCTIONS_NODE_BLOCK_ON_ENTRY_POINT_ERROR을true로 설정합니다. 이 설정은 모든 모델 v4 앱에 권장되며 모든 진입점 오류가 Application Insights 로그에 표시되는지 확인합니다. 자세한 내용은 Azure Functions 용 앱 설정 참조를 참조하세요.함수 앱 로그에서 진입점 오류를 확인하세요. 다음 예제 쿼리는 지난 날 앱의 진입점 오류를 보는 방법을 보여 줍니다.
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"
- 앱에 루트에 host.json 있는 필수 폴더 구조와 function.json 파일이 포함된 각 함수의 폴더가 있는지 확인합니다.
Undici request는 생성자가 아닙니다.
함수 앱 로그에서 다음 오류가 발생하면 다음을 수행합니다.
System.Private.CoreLib: 함수를 실행하는 동안 예외: Functions.httpTrigger1. System.Private.CoreLib: 결과: 실패 예외: undici_1.Request가 생성자가 아닙니다.
Node.js 버전 22.x 이상을 사용하고 있는지 확인합니다.
Azure Functions 런타임을 검색하지 못했습니다.
함수 앱 로그에서 다음 오류가 발생하면 다음을 수행합니다.
경고: Azure Functions 런타임을 검색하지 못했습니다. "@azure/functions" 패키지를 테스트 모드로 전환하면 모든 기능이 지원되지 않습니다.
package.json 파일에서 applicationinsights에 대한 참조를 확인하고 버전이 ^2.7.1 이상인지 확인하세요. 버전을 업데이트한 후 실행합니다. npm install
HTTP 스트림이 작동하지 않음
HTTP 스트리밍이 작동하지 않는다면:
- 패키지 버전이 4.3.0 이상인지 확인하세요
@azure/functions. - Ensure Azure Functions runtime version은 4.28 또는 이후입니다.
-
app.setup({ enableHttpStream: true })가 호출되는지 확인하세요. - Verify
FUNCTIONS_REQUEST_BODY_SIZE_LIMIT는 대용량 데이터에 맞게 설정되어 있습니다.
훅이 실행되지 않음
후크가 작동하지 않는 경우:
- 프로그래밍 모델 v4를 사용하고 있는지 확인하세요.
- 훅 등록 문법 검증:
app.hook.preInvocation()또는app.hook.appStart(). - 함수 정의 전에 훅을 등록하는지 확인하세요.
- 트리거 필터링을 검토해 보세요. 훅이 특정 함수 유형에만 적용되어야 하는지 확인하세요.
TypeScript 컴파일 문제
TypeScript 고유 문제에 대해:
빌드 실패:
-
tsconfig.json에 빌드 출력을 가리키는 올바른outDir가 있는지 확인하세요 - v3 모델에서
scriptFile가 컴파일된.js파일을 가리키고.ts는 가리키지 않도록 하세요. - 모든 TypeScript 의존성이 설치되어 있는지 확인하세요:
npm install --save-dev typescript @types/node
타입 오류:
- 최신 타입 정의를 위한 업데이트
@azure/functions패키지 - 적절한 임포트를 사용하세요:
import { app, HttpRequest, InvocationContext } from '@azure/functions' - 함수 서명이 기대되는 유형과 일치하는지 검증합니다
모듈 해석 문제
모듈 오류를 찾을 수 없음:
- 모든 의존성이 설치되었는지 확인하기 위해 실행하세요
npm install - 배포 패키지에 체크
node_modules폴더가 존재합니다 - ES 모듈의 경우, 파일 이름이
.mjs확장자를 사용하거나package.json에"type": "module"가 있는지 확인하세요. - TypeScript 컴파일 후 상대 가져오기 경로가 올바르는지 확인하세요
환경 및 구성 문제
누락된 환경 변수:
- 로컬 개발을 위해
local.settings.json에 변수를 추가합니다 - Azure Portal에서 클라우드 배포용 애플리케이션 설정
- 값에 액세스하려면
process.env["VARIABLE_NAME"]을 사용하세요
로그 기록 문제:
- 기능별 로그에는
context.log()대신console.log()을 사용하세요 - Application Insights 연결 문자열이 설정되어 있는지 확인하세요
- 필터링을 위해 로그 레벨
host.json을 확인하세요
Microsoft 도움말 보기
다음 방법 중 하나로 Microsoft 더 많은 도움을 받을 수 있습니다.
- Azure Functions Node.js 리포지토리에서 알려진 문제를 검색합니다. 언급된 문제가 표시되지 않으면 새 문제를 만들고 어떤 일이 일어났는지 알려주세요.
- 이 가이드를 사용하여 문제를 진단할 수 없는 경우 Microsoft 지원 엔지니어를 사용하여 애플리케이션 문제를 진단할 수 있습니다. Microsoft 다양한 지원 계획을 제공합니다. Azure 포털의 함수 앱 페이지의 지원 + 문제 해결 섹션에서 지원 티켓을 만듭니다.