사용자 정의 변수 정의하기

사용자 정의 변수(custom variables)는 n8n 워크플로에서 값을 저장하고 재사용할 수 있게 해주는 읽기 전용 변수예요. 인스턴스 전체에서 쓰는 전역 변수이거나 특정 프로젝트 안에서만 쓰는 프로젝트 범위 변수일 수 있습니다. 변수는 인스턴스 소유자와 관리자만 만들 수 있어요.

출처: 공식문서

본문

기능 가용성:

n8n Cloud: Pro, Enterprise

Self-hosted: Business, Enterprise

변수는 인스턴스 소유자와 관리자만 만들 수 있습니다.

변수 범위와 가용성:

전역 변수(Global variables): n8n 인스턴스의 모든 프로젝트에서 모든 사람이 사용할 수 있습니다.

프로젝트 범위 변수(Project-scoped variables): 생성된 특정 프로젝트 안에서만 사용할 수 있습니다.

프로젝트 범위 변수는 n8n 1.118.0부터 사용할 수 있습니다. 이전 버전은 왼쪽 메뉴에서 접근하는 전역 변수만 지원합니다.

변수 만들기

Variables 탭은 개요 페이지나 특정 프로젝트에서 접근할 수 있습니다.

새 변수를 만들려면:

Variables 탭에서 Add Variable을 선택합니다.
Key와 Value를 입력합니다. 키 최대 길이는 50자, 값 최대 길이는 1000자입니다. n8n은 키·값에 사용할 수 있는 문자를 대문자·소문자·숫자·밑줄(A-Z, a-z, 0-9, _)로 제한합니다.
Scope를 선택합니다(개요 페이지에서 만들 때만 사용 가능):
- Global: 변수가 n8n 인스턴스의 모든 프로젝트에서 사용 가능합니다.
- Project: 변수가 특정 프로젝트 안에서만 사용 가능합니다(프로젝트를 선택할 수 있음).
- 프로젝트 페이지에서 만들면 범위는 자동으로 그 프로젝트로 설정됩니다.
Save를 선택합니다. 이제 변수는 범위에 따라 워크플로에서 사용할 수 있습니다.

변수 편집·삭제하기

Variables 탭에서 변경할 변수 위에 마우스를 올립니다.
Edit 또는 Delete를 선택합니다.

워크플로에서 변수 사용하기

Code 노드와 표현식에서 변수에 접근할 수 있습니다:

// 변수 접근하기
$vars.<variable-name>

모든 변수는 문자열입니다.

워크플로 실행 중에는 n8n이 변수를 변수 값으로 대체합니다. 변수에 값이 없으면 n8n은 그 값을 undefined로 취급합니다. 이 경우 워크플로가 자동으로 실패하지는 않습니다.

변수 우선순위: 프로젝트 범위 변수가 전역 변수와 같은 키를 가질 때, 해당 프로젝트의 워크플로 안에서는 프로젝트 범위 변수 값이 전역 변수 값을 덮어씁니다.

변수는 읽기 전용입니다. 값을 바꾸려면 UI를 사용해야 합니다. 워크플로 안에서 커스텀 데이터를 설정·접근해야 한다면 Workflow static data를 사용하세요.

더 알아보기

표현식: 노드 파라미터를 동적으로 채우는 문법
Workflow static data: 워크플로 안에서 커스텀 데이터 저장·접근