업무 자동화를 설계하다 보면 기본 제공 노드만으로는 해결이 안 되는 복잡한 상황을 자주 마주하게 됩니다. 처음에는 Edit Fields, If, Merge 같은 기본 노드만으로도 충분해 보이지만, 실제 운영에 들어가면 외부 API 응답 구조가 너무 깊게 중첩되어 있거나, 여러 필드를 한 번에 계산해서 다음 단계로 넘겨야 하거나, 조건에 따라 완전히 다른 데이터 구조를 만들어야 하는 순간이 분명히 옵니다. 이때부터는 노드를 계속 이어 붙이는 방식이 오히려 더 길고 더 불안정해질 수 있습니다.
이럴 때 핵심이 되는 것이 예전의 Function 노드, 현재 기준으로는 Code 노드입니다. 아직도 많은 글에서는 Function 노드라는 표현을 그대로 쓰지만, 지금 n8n 문서와 실제 UI 기준으로는 Code 노드로 이해하는 편이 더 정확합니다. 중요한 건 이름보다 역할입니다. 이 노드는 기본 노드만으로는 길어지는 데이터 가공을 짧고 명확하게 정리하게 해주는 도구에 가깝습니다.
저도 처음에는 이 노드를 “정말 어쩔 수 없을 때만 쓰는 마지막 수단”처럼 봤습니다. 그런데 몇 번 직접 써보니 오히려 반대였습니다. 노드가 다섯 개, 여섯 개씩 길게 이어져야 겨우 되는 구조가 자바스크립트 몇 줄로 더 읽기 쉬워지는 경우가 많았습니다. 문제는 자바스크립트 문법 자체보다, n8n이 데이터를 어떤 구조로 넘겨주는지, 현재 아이템과 전체 입력을 어떻게 구분해야 하는지, 그리고 무엇을 Code 노드 안에서 해결하고 무엇은 그냥 기본 노드로 두는 게 더 나은지를 구분하는 일이었습니다.
실제로는 연결 성공보다, 같은 실수를 반복하지 않게 구조를 잡는 단계가 더 오래 남는다. 예전 Function 노드 관점으로만 보면 현재 Code 노드의 데이터 흐름을 놓치기 쉽다. 이름보다 입력 구조와 반환 방식 이해가 더 중요하다.
그래서 이 글에서는 예전 Function 노드 감각을 현재 Code 노드 기준으로 다시 정리해봅니다. 데이터 구조를 어떻게 이해해야 하는지, $json과 $input.all()을 언제 어떻게 써야 하는지, 어떤 패턴이 실무에서 자주 쓰이는지, 그리고 외부 라이브러리와 날짜 처리, 예외 처리까지 어디까지 가능한지를 실무형 관점으로 풀어보겠습니다.
n8n Function노드 기초 데이터 구조와 Items의 이해
n8n에서 모든 데이터는 아이템 단위로 움직입니다. 이 부분을 제대로 이해하지 못하면, 자바스크립트 실력이 아무리 좋아도 에러에 계속 막히게 됩니다. 기본적으로 n8n은 데이터를 배열로 관리하고, 배열 속 각각의 요소는 json 키를 가진 객체로 전달됩니다.
예를 들어 이전 노드에서 이메일 주소 5개를 받아왔다면, Code 노드 안에서는 그 5개가 입력 아이템으로 들어옵니다. 여기서 가장 먼저 이해해야 할 것은 “지금 하나의 아이템을 보고 있는가, 아니면 전체 아이템 묶음을 보고 있는가”입니다. 실무에서는 이 차이를 이해하지 못해서 값을 하나만 처리하거나, 반대로 전체를 의도치 않게 다시 순회하는 실수가 아주 흔합니다.
실제로 운영하다 보면 많이 놓치는 부분이 바로 여기입니다. 값이 안 나오는 이유가 코드 문법 때문이 아니라, 지금 내가 보고 있는 단위가 현재 아이템인지 전체 입력인지 헷갈려서 생기는 경우가 훨씬 많습니다. 그래서 Code 노드에 익숙해질수록 문법보다 입력 구조를 먼저 확인하는 습관이 더 중요해집니다.

1. 입력 데이터에 접근하기
현재 아이템 하나를 기준으로 볼 때는 보통 $json이 가장 직관적입니다. 예를 들어 현재 아이템의 이메일 값을 보려면 $json.email처럼 접근하면 됩니다. 반대로 전체 입력을 한 번에 순회하거나 합계를 계산하거나, 모든 아이템을 모아서 새로운 배열을 만들고 싶다면 $input.all()을 쓰는 편이 자연스럽습니다.
// 현재 아이템 하나 기준
return [
{
json: {
email: $json.email
}
}
];
// 전체 입력 기준
const items = $input.all();
return items.map(item => ({
json: {
email: item.json.email
}
}));처음에는 이 둘이 비슷해 보여도 결과는 크게 달라집니다. 현재 아이템을 봐야 할 자리에서 전체 입력을 다시 순회하면 중복된 결과가 나오기 쉽고, 반대로 전체 합계를 내야 하는 자리에서 현재 아이템만 보면 계산이 전혀 맞지 않게 됩니다.
2. 출력 데이터의 필수 형식 이해
초보자들이 가장 자주 하는 실수 중 하나는 return 형식을 잘못 맞추는 경우입니다. n8n은 결과를 아이템 배열 형태로 이해하기 때문에, 단순 문자열이나 일반 객체만 반환하면 의도한 대로 다음 노드가 받지 못할 수 있습니다.
| 구분 | 설명 | 코드 예시 |
|---|---|---|
| 올바른 구조 | 배열 안에 json 키를 가진 객체 | [{ json: { id: 1 } }] |
| 잘못된 구조 | 일반 객체만 반환 | { id: 1 } |
실패 사례는 대체로 비슷합니다. 데이터를 잘 가공해놓고도 마지막 return 형식을 단순 객체로 내보내서 다음 노드에서 값이 안 보이는 경우가 많습니다. 그래서 Code 노드를 디버깅할 때는 로직보다 먼저 “지금 return 구조가 n8n이 기대하는 형태인가”를 확인하는 편이 훨씬 빠릅니다.
n8n Function노드 기초 활용 패턴 4가지
이론을 익혔다면 이제 실제 워크플로우에서 Code 노드가 어떻게 쓰이는지 구체적으로 살펴볼 차례입니다. 실무에서는 주로 데이터 형태를 바꾸거나, 여러 노드에서 온 값을 하나로 합치거나, 중첩 구조를 평면화하거나, 여러 아이템을 집계하는 데 Code 노드가 자주 활용됩니다.
실제로 운영하다 보면 기본 노드만으로도 구현은 가능합니다. 문제는 노드가 너무 많아지면 로직을 다시 읽기가 어려워진다는 점입니다. 이때 Code 노드가 빛나는 구간은 “짧은 코드가 긴 노드 체인보다 더 명확할 때”입니다. 반대로 단순 필드 하나 추가하는 정도라면 Code 노드를 안 쓰는 편이 더 낫습니다.

1. 데이터 필터링과 조건부 로직 적용
표준 If 노드는 단일 조건 처리에 알맞지만, “A이면서 B이거나 C인 경우”처럼 조건이 길어지면 코드로 처리하는 것이 더 명확해질 때가 많습니다. 예를 들어 여러 필드를 보고 하나의 상태를 계산해야 하거나, 특정 값 조합일 때만 새로운 필드를 만들어야 하는 경우가 그렇습니다.
const items = $input.all();
return items.filter(item => item.json.status === 'active' && item.json.score >= 80).map(item => ({
json: {...item.json,
priority: 'high'
}
}));이런 식으로 조건과 변환을 한곳에 정리하면, 여러 개의 If와 Edit Fields를 길게 이어 붙이는 것보다 훨씬 읽기 쉬워질 수 있습니다.
2. 날짜 및 텍스트 데이터 포맷팅
여러 시스템을 연동하다 보면 날짜 형식이 서로 달라 오류가 자주 납니다. 이럴 때 단순 new Date()만 믿고 가기보다, n8n이 날짜와 시간 처리에서 권장하는 Luxon 기반 접근을 함께 이해하는 편이 더 안정적입니다. 특히 워크플로우 타임존과 맞물리는 경우에는 이 차이가 더 크게 느껴집니다.
const items = $input.all();
return items.map(item => ({
json: {...item.json,
created_date: item.json.created_at
? item.json.created_at.slice(0, 10): null
}
}));복잡한 날짜 연산이 필요한 경우에는 Luxon 기반 접근을 검토하는 편이 좋습니다. 단순 문자열 잘라내기와 날짜 계산은 완전히 다른 문제라서, 이 구분을 못 하면 나중에 시간대가 어긋나기 쉽습니다.
3. 중첩된 JSON 데이터 평면화(Flatten)
API 응답 데이터가 여러 단계로 중첩되어 있을 때, 이를 구글 시트나 데이터베이스처럼 표 구조로 정리하려면 데이터를 펼치는 과정이 필요합니다. 이때 Code 노드는 꽤 강력합니다. 반복문이나 map()을 적절히 쓰면 복잡한 중첩 데이터를 한 번에 다시 만들 수 있습니다.
const items = $input.all();
return items.map(item => ({
json: {
user_id: item.json.user?.id ?? null,
user_name: item.json.user?.name ?? null,
user_email: item.json.user?.profile?.email ?? null
}
}));많이 놓치는 부분은 없는 필드를 그대로 접근하다가 에러를 내는 것입니다. 그래서 중첩 구조를 평면화할 때는 optional chaining이나 기본값 처리를 같이 두는 편이 훨씬 안전합니다.
4. 집계와 요약값 계산
여러 아이템의 총합, 평균, 건수처럼 요약값을 만들 때는 reduce()가 실무에서 자주 쓰입니다. 기본 노드만으로도 흉내 낼 수 있지만, 계산 로직이 조금만 복잡해지면 Code 노드가 훨씬 짧고 분명해지는 경우가 많습니다.
const items = $input.all();
const total = items.reduce((sum, item) => sum + (item.json.amount || 0), 0);
return [
{
json: {
total_amount: total,
item_count: items.length
}
}
];이런 집계는 보고서 자동화나 매출 요약, 에러 건수 체크 같은 곳에서 생각보다 자주 쓰입니다. 특히 “전체를 한 번에 보고 싶은가, 각 아이템을 그대로 유지하고 싶은가”를 먼저 정해두면 구조가 훨씬 덜 꼬입니다.
📌 핵심 포인트 & 주의사항
실무자의 시선에서 보면, 최근 n8n에서는 예전 Function 노드 개념이 Code 노드로 통합되어 이해되는 편이 더 정확합니다. 특히 “모든 아이템 한 번에 실행” 관점과 “현재 아이템 기준으로 처리” 관점의 차이를 이해하는 것이 매우 중요합니다. 전체 데이터를 한 번에 가공하거나 합칠 때는 전자 모드가 유리하고, 각각의 아이템 값을 조금씩만 바꿀 때는 후자 관점이 더 직관적입니다. Code 노드의 기초를 익힐 때 이 두 처리 단위의 차이부터 정확히 이해하는 것이 무엇보다 중요합니다.
실전에서 자주 만나는 문제와 해결 포인트
1. 외부 라이브러리 사용은 환경에 따라 다릅니다
외부 라이브러리 사용은 가장 자주 오해하는 부분 중 하나입니다. 셀프호스팅에서는 외부 npm 모듈을 사용할 수 있지만, 그냥 코드에서 바로 가져다 쓰는 구조가 아닙니다. 실제 실행 환경에 해당 모듈이 설치되어 있어야 하고, 허용 환경 변수 설정도 함께 들어가야 합니다. Docker 환경이라면 보통 커스텀 이미지에 모듈을 포함시키는 쪽으로 접근하게 됩니다.
반대로 n8n Cloud에서는 외부 npm 모듈을 자유롭게 사용하는 방식으로 보면 안 됩니다. 그래서 “환경 변수만 넣으면 어디서나 된다” 식으로 이해하면 운영 단계에서 바로 막히기 쉽습니다.
2. 날짜 처리에서는 Luxon을 먼저 검토하는 편이 낫습니다
날짜 처리는 많은 사용자가 단순 Date 객체로 시작하지만, 실제로는 타임존과 문자열 포맷 문제가 쉽게 섞입니다. n8n은 날짜와 시간을 다룰 때 Luxon 기반 접근을 문서에서 안내하고 있기 때문에, 복잡한 날짜 계산이 필요하다면 외부 패키지를 새로 찾기보다 먼저 Luxon 기준으로 생각하는 편이 더 안정적입니다.
처음에는 괜찮아 보여도 실제 운영에 들어가면 “어제 기준”, “오늘 자정 이후”, “영업일 기준 3일 뒤” 같은 요구가 금방 붙습니다. 이때 단순 문자열 비교나 로컬 Date 처리만으로 버티면 시간이 갈수록 더 자주 꼬입니다.
3. 파이썬은 자바스크립트와 완전히 같다고 보면 안 됩니다
최근에는 Code 노드의 Python 지원을 보고 자바스크립트와 거의 똑같이 쓸 수 있다고 생각하는 경우도 많습니다. 하지만 실제로는 지원 범위가 다릅니다. 일반적인 n8n 데이터 구조 활용과 내장 메서드 접근 관점에서는 자바스크립트 쪽이 훨씬 자연스럽습니다.
그래서 실무에서는 기본적으로 자바스크립트를 중심으로 익히는 편이 훨씬 유리합니다. 파이썬이 더 익숙하더라도, n8n의 내장 데이터 접근 패턴과 예제를 따라가려면 자바스크립트 쪽 이해가 먼저 잡혀 있는 편이 더 안정적입니다.
4. 실패 사례는 대체로 비슷합니다
많이 틀리는 지점은 반복됩니다. 첫째, 현재 아이템 하나만 봐야 하는데 전체 입력을 순회해서 결과가 중복되는 경우. 둘째, return 형식을 일반 객체로 내보내서 다음 노드가 값을 제대로 받지 못하는 경우. 셋째, 없는 필드를 그대로 참조하다가 중간에 에러가 나는 경우입니다. 코드 문법이 어려워서보다, n8n 데이터 구조를 평범한 자바스크립트 객체처럼만 보고 접근해서 생기는 문제가 더 많습니다.
그래서 Code 노드를 디버깅할 때는 멋진 코드보다 기본기를 먼저 봐야 합니다. 지금 입력 구조가 무엇인지, 어떤 단위로 처리 중인지, return 형식이 맞는지, 없는 값에 대한 기본값 처리가 있는지를 먼저 확인하면 훨씬 빨리 풀립니다.
직접 확인해보면 좋은 테스트 예시
1. 현재 아이템과 전체 입력 차이 테스트
테스트 예시
입력 데이터:
[
{"json": {"price": 100}},
{"json": {"price": 200}},
{"json": {"price": 300}}
]
코드 A:
return [{ json: { value: $json.price } }];
코드 B:
const items = $input.all();
return [{ json: { total: items.reduce((sum, item) => sum + item.json.price, 0) } }];기대 결과
A는 현재 아이템 기준 값, B는 전체 아이템 합계를 보여줘야 합니다.
실제 확인 포인트
지금 내가 현재 아이템을 봐야 하는지, 전체 배열을 봐야 하는지를 잘못 잡으면 결과가 어떻게 달라지는지 확인합니다.
2. 중첩 JSON 평면화 테스트
테스트 예시
입력:
{
"customer": {
"profile": {
"email": "[email protected]"
}
}
}기대 결과
중첩된 경로에서 email만 꺼내 평면 구조로 다시 만들 수 있어야 합니다.
실제 확인 포인트
경로가 틀릴 때 undefined가 어떻게 나타나는지, 기본값 처리가 필요한지 같이 확인합니다.
3. 날짜 처리 테스트
테스트 예시
입력:
{
"created_at": "2026-03-23T09:00:00+09:00"
}기대 결과
단순 문자열 처리와 날짜 계산은 구분해서 봐야 하며, 복잡한 연산은 Luxon 기준 접근이 더 안정적이어야 합니다.
실제 확인 포인트
날짜를 문자열처럼 자를 때와 실제 날짜 계산을 할 때 결과 차이가 어떻게 나는지 확인합니다.
4. 예외 처리 테스트
테스트 예시
입력:
[
{"json": {"price": 100}},
{"json": {}}
]기대 결과
없는 필드를 바로 계산하면 실패할 수 있으므로, 기본값 처리나 예외 처리 전략이 필요합니다.
실제 확인 포인트
기본값 없이 돌렸을 때와 안전하게 기본값을 준 경우 결과가 어떻게 달라지는지 확인합니다.
실제 검증 실행 결과
실제 검증 기준으로 보면 가장 먼저 차이가 난 건 자바스크립트 문법보다 입력 구조 이해였습니다. 현재 아이템 기준으로 봐야 할 곳에서 전체 입력을 다시 순회하면 결과가 중복됐고, 반대로 전체 집계를 해야 하는 곳에서 현재 아이템만 보면 합계가 전혀 맞지 않았습니다. 또 날짜 처리에서는 단순 문자열 조작보다 날짜 계산이 필요한 순간부터 구조를 다시 잡아야 했고, 외부 패키지도 단순 허용이 아니라 실제 설치와 환경 구성이 함께 필요하다는 점이 분명히 드러났습니다. 결국 Code 노드는 코드를 잘 쓰는 것보다, n8n이 넘겨주는 데이터를 지금 어떤 단위로 보고 있는지를 먼저 이해할 때 훨씬 빠르게 안정화된다는 점이 가장 크게 체감됐습니다.
예전 Function 노드에서 현재 Code 노드 감각으로 넘어올 때는 코드 자체보다 운영 구조를 같이 보는 편이 훨씬 덜 헷갈린다. 특히 self-hosted 기준 재배포와 버전 관리 흐름은 [관련 글: n8n Git 연동으로 워크플로우 버전 관리 시스템 구축하기 더 알아보기]와 [관련 글: n8n NAS 설치 Docker로 자동화 서버 구축하기 더 알아보기]를 같이 보면 감이 빨라진다.
이어서 살펴보면 좋은 내용
- [관련 글: n8n Git 연동으로 워크플로우 버전 관리 시스템 구축하기 더 알아보기]
- [관련 글: n8n NAS 설치 Docker로 자동화 서버 구축하기 더 알아보기]
- [관련 글: n8n 구글클라우드로 평생 무료 운영하는 실전 가이드 더 알아보기]
- [관련 글: n8n oracle cloud 무료 서버 설치 가이드 더 알아보기]
FAQ: 자주 묻는 질문
Q. 자바스크립트를 전혀 모르는 사람도 예전 Function 노드 개념을 지금 Code 노드 기준으로 배울 수 있을까요?
A. 네, 가능합니다. n8n에서는 복잡한 프로그래밍 실력보다 데이터가 아이템 배열 구조로 흐른다는 것을 이해하는 것이 훨씬 중요합니다. 현재 아이템과 전체 입력의 차이, 그리고 반환 구조를 먼저 이해하면 기본적인 실무 적용은 충분히 가능합니다.
Q. 외부 라이브러리(예를 들어 lodash나 moment 등)를 쓸 수 있나요?
A. 셀프호스팅이라면 가능합니다. 다만 단순히 환경 변수만 넣는다고 끝나는 것이 아니라, 실제 실행 환경에 모듈이 설치되어 있어야 하고 허용 설정도 함께 들어가야 합니다. 반대로 Cloud에서는 자유롭게 외부 npm 모듈을 쓰는 방식으로 보면 안 됩니다.
자동화의 진정한 힘은 기본 노드들이 다루지 못하는 예외 상황까지 얼마나 유연하게 대처하는지에 달려 있습니다. 현재 기준으로 보면 예전 Function 노드를 이해하는 일은 결국 Code 노드를 제대로 이해하는 일과 같습니다. 처음에는 낯선 데이터 구조에 헤매며 에러도 자주 만나겠지만, 한 번 익숙해지면 자동화 설계의 시야가 확연히 넓어집니다.
실제로 운영하다 보면 체감되는 이득도 분명합니다. $json과 $input.all() 차이, 반환 형식, 날짜 처리, 외부 모듈 허용 범위만 제대로 이해해도 “왜 값이 중복되지?”, “왜 다음 노드가 못 받지?”, “왜 패키지가 안 되지?” 같은 시간을 크게 줄일 수 있습니다. 결국 Code 노드는 화려한 기술보다 기본 구조를 정확히 이해했을 때 가장 강해집니다.
실제로 적용할 때 체크할 부분
이 글을 읽고 바로 적용해보려면 먼저 지금 가장 길게 얽혀 있는 Set/If/Edit Fields 조합 워크플로우 하나를 골라, 정말 Code 노드 하나로 더 명확해질 수 있는 구간이 있는지부터 보는 것이 좋습니다. 그다음에는 현재 아이템용 처리인지, 전체 배열용 처리인지 먼저 정하고 코드를 짜면 훨씬 덜 헷갈립니다.
다음 단계 학습용으로는 [관련 글: n8n Git 연동으로 워크플로우 버전 관리 시스템 구축하기 더 알아보기], [관련 글: n8n NAS 설치 Docker로 자동화 서버 구축하기 더 알아보기], [관련 글: n8n 구글클라우드로 평생 무료 운영하는 실전 가이드 더 알아보기], [관련 글: n8n oracle cloud 무료 서버 설치 가이드 더 알아보기]를 순서대로 같이 보면 운영과 배포 감각까지 함께 잡기 좋다.
그리고 가능하다면 테스트 입력을 고정해 두고, $json 기준 코드와 $input.all() 기준 코드를 각각 한 번씩 돌려보는 것이 좋습니다. 같은 데이터라도 어떤 단위로 보고 있는지에 따라 결과가 크게 달라지는 것을 직접 보면 감이 훨씬 빨리 잡힙니다.
참고 자료: n8n Documentation – Code in n8n | n8n Documentation – Using the Code node | n8n Documentation – Built-in methods and variables | n8n Documentation – Date and time with Luxon | n8n Documentation – Enable modules in Code node
예전 Function 노드 관점으로만 보면 현재 Code 노드의 데이터 흐름을 놓치기 쉽다. 이름보다 입력 구조와 반환 방식 이해가 더 중요하다. 그래서 이 글도 단순 기능 소개보다, 실제로 다시 손댈 때 바로 체크할 수 있는 기준이 남도록 흐름을 정리하는 쪽이 더 유용하다.
