환경 변수

환경 변수를 사용하면 코드를 변경할 필요 없이 환경에서 실행 중인 애플리케이션 프로세스에 변수를 추가할 수 있습니다. 환경 변수는 안전하게 저장되므로 다음과 같은 활용 사례에 적합합니다.

  • 타사 통합을 위한 API 키
  • 애플리케이션 로직의 기능 플래그
  • 환경 간에 다르거나 비밀이 아닐 수 있는 구성

환경 변수는 앱 서버에서만 액세스할 수 있습니다. 프록시 및 엣지 기능을 포함한 엣지 서비스의 동작을 수정할 수 없습니다.

다음 튜토리얼에 따라 환경 변수를 설정한 다음, PWA Kit 사이트에서 변수를 사용하도록 코드를 구현합니다. 특정 요구 사항에 따라 코드를 맞춤화할 수 있습니다. 튜토리얼에서는 다음 작업을 수행하는 방법을 보여 줍니다.

변경 사항을 프로덕션 환경에 배포하기 전에 로컬 컴퓨터에서 단계를 테스트한 다음, 비프로덕션 환경에서 테스트하는 것이 좋습니다. 자세한 지침은 모범 사례, 환경 변수 문제 해결 및 로컬 디버깅을 참조하십시오.

환경 변수:

새 환경 변수를 도입할 때 먼저 API 또는 런타임 관리자를 통해 설정합니다. 재배포가 완료될 때까지 기다린 다음, 이를 사용하는 새 번들을 배포합니다.

환경 변수 설정, 업데이트 및 설정 취소

projects_target_env_var_partial_update 사용:

기존 환경 변수를 설정 취소하려면 값을 null로 설정합니다.

환경 변수를 수정하면 환경이 다시 배포됩니다. 업데이트된 값은 배포가 완료되면 사용할 수 있습니다.

모든 환경 변수 가져오기

projects_target_env_var_list 사용:

환경 변수를 생성하거나, 업데이트하거나, 제거하거나, 보려면:

  1. Runtime Admin에 로그인합니다. Runtime Admin에 대한 액세스 권한을 얻으려면 Managed Runtime 관리를 참조하십시오.
  2. 프로젝트의 Overview(개요) 페이지로 이동합니다.
  3. 환경 변수를 관리할 환경의 이름을 클릭합니다.
  4. 왼쪽 탐색 영역에서 환경 변수를 클릭합니다.
  • 앱에 적합한 환경 변수 이름을 선택합니다. 설명이 포함된 이름 사용: 팀이 쉽게 이해할 수 있도록 환경 변수에 대해 명확하고 간결한 이름을 선택합니다.
  • 코드에서 API 키와 같은 민감한 정보를 하드 코딩하지 마십시오. 환경 변수를 사용하여 보안을 유지하십시오.
  • 페이지에 직렬화될 데이터에 환경 변수를 전달하지 마십시오. 환경 변수 데이터가 유출되지 않는지 확인하는 테스트를 추가하는 것이 좋습니다.
  • getProps 또는 react-query 후크에서 환경 변수를 반환하지 마십시오.
  • 서버 측에서만 환경 변수를 사용하십시오. 기본적으로 환경 변수는 클라이언트 쪽에 노출되지 않습니다. 클라이언트 측(예: 구성 파일)에 노출하도록 선택할 수 있지만 값 노출이 보안 모범 사례에 부합하는지 확인하십시오.
  • 환경 변수를 로컬 컴퓨터에서 테스트한 다음, 프로덕션 환경에 배포하기 전에 비프로덕션 환경에서 테스트하십시오. 이렇게 하면 로컬에서 신속하게 문제를 해결한 다음, 프로덕션 환경에 배포하기 전에 사이트 동작을 시뮬레이션하고, 기능을 검증하고, 사용자 수용 테스트를 수행할 수 있습니다.
  • 정의되지 않은 환경 변수로 인한 오류를 방지하기 위해, 환경 변수를 사용하는 코드에 오류 처리를 포함합니다.
  • 무단 수정을 방지하기 위해, 환경 변수에 대한 액세스를 제어하십시오.
  • 각 환경 변수의 용도와 구성을 문서화십시오. 이는 신규 개발자를 온보딩하고 문제를 해결하는 데 도움이 됩니다.

환경 변수의 사용에는 다음과 같은 제약 조건이 적용됩니다.

  • 환경 변수 값은 문자열이어야 합니다. 복잡한 값을 저장하려면 JSON을 문자열로 인코딩합니다.
  • 각 환경에는 환경 변수를 100개까지만 설정할 수 있습니다.
  • 환경에 대해 설정되는 환경 변수 값의 최대 크기는 32KB입니다.
  • 환경 변수 이름은 512자 이하여야 하며, AWS, MRT, X_MRT, MOBIFY, X_MOBIFY, SSR_PROXY, NODE 등의 예약된 접두사로 시작할 수 없습니다.
  • BUNDLE_ID, DEPLOY_ID, DEPLOY_TARGET, EXTERNAL_DOMAIN_NAME, HANDLER, LAMBDA_RUNTIME_DIR, LAMBDA_TASK_ROOT, NODE_ENV, REDIRECT_BUCKET, REDIRECT_KEY, REDIRECT_UPDATE, REMOTE, X_AMZN_TRACE_ID 등의 예약된 이름은 환경 변수 이름으로 사용할 수 없습니다.

이 섹션에서는 환경 변수를 사용하는 동안 발생할 수 있는 일반적인 오류에 대해 제안된 해결 방법을 제공합니다.

코드에서 변수가 누락되었다는 Error가 표시됩니다.

원인: 코드가 호출하는 환경 변수가 설정되지 않았습니다.

제안된 솔루션: projects_target_env_var_partial_update API 엔드포인트를 호출하여 해당 환경 변수를 설정합니다.

코드가 환경 변수를 찾을 수 없다는 오류 메시지를 로깅합니다.

원인: 코드에 오타가 있거나 잘못된 환경 변수 이름이 사용되어 코드에서 환경 변수를 찾을 수 없습니다.

제안된 솔루션: 코드에서 환경 변수 이름의 철자를 올바르게 입력하고 올바른 환경 변수 이름을 사용했는지 확인합니다. 설정된 변수의 전체 목록을 보려면 projects_target_env_var_list API 엔드포인트를 호출하여 환경 변수 이름을 확인합니다.

환경 변수를 설정하기 위한 API 호출이 실패합니다.

원인: 환경 변수 이름이 제약 조건에 부합하지 않을 수 있습니다. 예를 들어 환경 변수 값의 크기가 32KB를 초과합니다.

제안된 솔루션: 환경 변수가 제약 조건에 부합하는지 확인합니다.

인증 오류는 API 키 사용과 관련한 코드를 실행할 때 발생합니다.

원인: 환경 변수를 설정할 때 사용한 API 키가 올바른 형식이 아니거나 누락되었습니다.

제안된 솔루션: 환경 변수에 의해 저장된 API 키가 올바른지 확인합니다. 필요한 경우 projects_target_env_var_partial_update API 엔드포인트를 호출하여 API 키를 수정합니다.

네트워크 오류로 인해 fetch 요청이 실패합니다.

원인: 코드에서 호출된 API 엔드포인트의 URL이 올바르게 정의되지 않았거나 잘못되었을 수 있습니다. 예를 들어 CMS(컨텐츠 관리 시스템) 엔드포인트의 URL이 올바르지 않습니다.

제안된 솔루션: 코드의 API 엔드포인트에 대한 URL이 올바른지 확인합니다.