C++/MFC에서 LNK2019 링커 오류, 원인부터 단계별 해결까지 완벽 정리

빌드까지는 깔끔하게 통과했는데, 마지막 링크 단계에서 갑자기 빨간 글씨로 error LNK2019: 확인할 수 없는 외부 기호가 쏟아지는 경험은 C++ 개발자라면 누구나 한 번쯤 겪습니다. 특히 MFC 프로젝트에서는 이 오류가 함수 하나 때문이 아니라 라이브러리 설정, 호출 규약, 헤더 불일치 등 여러 갈래에서 동시에 터지기 때문에 원인을 짚기가 까다롭습니다.

이 글에서는 LNK2019가 "왜" 발생하는지 컴파일·링크 단계의 동작 원리부터 짚고, 실무에서 바로 적용할 수 있는 점검 순서를 단계별로 정리합니다.

1. LNK2019는 컴파일 오류가 아니다 — 링커의 신호

C++ 빌드는 크게 두 단계로 나뉩니다.

• 컴파일(Compile): 각 .cpp 파일을 개별적으로 번역해 .obj 오브젝트 파일을 만든다. 이 단계에서는 함수의 "선언"만 있으면 통과한다.
• 링크(Link): 흩어진 오브젝트 파일과 라이브러리를 하나의 실행 파일로 묶는다. 이때 비로소 "선언만 있고 정의가 없는" 함수의 실제 구현체를 찾아 연결한다.

LNK2019는 바로 이 두 번째 단계, 즉 링커가 "어떤 심볼을 호출하는 코드는 있는데, 그 심볼의 실제 구현을 어디서도 찾지 못했다"고 보고하는 오류입니다. 다시 말해 컴파일러는 만족했지만, 링커는 약속된 함수의 본체를 발견하지 못한 상태입니다.

핵심을 한 줄로 요약하면 이렇습니다.

"쓰겠다고 약속(선언)은 했는데, 정작 구현(정의)이 어디에도 연결되지 않았다."

2. 오류 메시지 읽는 법

해결의 절반은 메시지를 정확히 읽는 데서 시작합니다. 전형적인 LNK2019 메시지는 다음과 같은 형태입니다.

error LNK2019: 확인할 수 없는 외부 기호 "void __cdecl CalculateScore(int)" (?CalculateScore@@YAXH@Z),
함수 "int __cdecl main(void)" (?main@@YAHXZ)에서 참조됩니다.

여기서 읽어야 할 정보는 세 가지입니다.

• 확인할 수 없는 외부 기호: 링커가 찾지 못한 함수/변수 이름 (위 예시는 CalculateScore)
• 데코레이트된 이름 (?CalculateScore@@YAXH@Z): C++ 네임 맹글링 결과. 호출 규약이나 인자 타입이 어긋났는지 추적하는 단서가 된다.
• 참조 위치: 그 심볼을 호출한 함수 (위 예시는 main)

즉 "main이 CalculateScore(int)를 호출했는데, 그 정의를 못 찾았다"는 뜻입니다. 어느 함수가, 어디서 호출됐는지 명확하므로 추측할 필요가 없습니다.

3. 단계별 해결 절차 (6가지 점검 포인트)

아래 순서대로 점검하면 대부분의 LNK2019는 잡힙니다.

3-1. 함수 정의가 실제로 존재하는가

가장 흔한 원인은 선언만 하고 정의(구현)를 빠뜨린 경우입니다. 헤더에는 시그니처를 적어두고 .cpp에 본체 작성을 깜빡한 상황이죠.

// score.h  — 선언 (약속)
void CalculateScore(int round);

// score.cpp — 정의 (구현). 이 블록이 없으면 LNK2019 발생
void CalculateScore(int round) {
    // 실제 점수 계산 로직
}

선언과 정의의 반환형·함수명·매개변수 개수와 타입이 한 글자라도 다르면 컴파일러는 둘을 별개의 함수로 취급하고, 링커는 여전히 구현을 못 찾습니다.

3-2. 정의가 담긴 cpp 파일이 빌드에 포함됐는가

score.cpp를 작성했더라도 그 파일이 솔루션 탐색기의 프로젝트에 추가되지 않았다면 컴파일조차 되지 않습니다. 파일이 회색으로 비활성화돼 있거나, 프로젝트에서 제외된 상태인지 확인하세요.

확인 경로: 솔루션 탐색기에서 해당 .cpp 우클릭 → 속성 → "빌드에서 제외"가 "아니요"인지 확인

3-3. 헤더 포함이 올바른가

호출 측에서 선언을 보지 못하면 컴파일 단계에서 다른 오류가 나지만, 잘못된 헤더를 포함하면 미묘한 불일치로 이어질 수 있습니다.

// main.cpp
#include "score.h"   // CalculateScore 선언이 든 헤더를 정확히 포함

3-4. 외부 라이브러리(.lib)가 링크됐는가

서드파티 SDK나 OpenGL, ws2_32 같은 시스템 라이브러리의 함수를 쓸 때, 헤더만 포함하고 .lib를 링크하지 않으면 LNK2019가 납니다. 두 가지 방법이 있습니다.

코드에서 직접 지정:

// 소켓 라이브러리를 코드에서 명시적으로 링크
#pragma comment(lib, "ws2_32.lib")

또는 프로젝트 설정에서 지정:

설정 경로: 프로젝트 속성 → 링커 → 입력 → 추가 종속성에 필요한라이브러리.lib 추가 추가로 링커 → 일반 → 추가 라이브러리 디렉터리에 .lib가 위치한 폴더 경로를 등록해야 합니다.

3-5. 플랫폼/구성이 일치하는가

x86용으로 빌드된 .lib를 x64 프로젝트에 링크하면 심볼을 못 찾습니다. 또한 Debug 라이브러리를 Release 구성에 넣어도 충돌이 납니다. 프로젝트의 **플랫폼(x86/x64)**과 **구성(Debug/Release)**이 라이브러리와 일치하는지 확인하세요.

3-6. 호출 규약과 extern "C"

C로 작성된 라이브러리를 C++에서 호출할 때 네임 맹글링 차이로 심볼이 어긋납니다. 이때는 선언을 extern "C"로 감싸야 합니다.

// C 라이브러리 함수를 C++에서 호출할 때
extern "C" {
    int legacy_init(const char* path);
}

4. MFC 프로젝트에서만 생기는 함정

MFC는 일반 C++ 콘솔 프로젝트와 빌드 설정이 다릅니다. MFC 프로젝트에서 LNK2019가 날 때 추가로 봐야 할 항목은 다음과 같습니다.

• MFC 사용 설정: 프로젝트 속성 → 고급 → "MFC 사용"이 "공유 DLL에서 MFC 사용" 또는 "정적 라이브러리에서 MFC 사용"으로 되어 있는지 확인. 이 값이 "표준 Windows 라이브러리 사용"이면 MFC 심볼을 못 찾습니다.
• 메시지 맵 매크로: BEGIN_MESSAGE_MAP / END_MESSAGE_MAP 사이의 핸들러가 클래스에 실제로 정의돼 있어야 합니다. 매크로에는 핸들러를 등록했는데 멤버 함수 구현을 안 했다면 LNK2019로 나타납니다.
• 유니코드/멀티바이트 일치: 라이브러리가 유니코드로 빌드됐는데 프로젝트가 멀티바이트면 문자열 관련 심볼이 어긋날 수 있습니다.

5. 흔한 실수와 엣지 케이스

• 인라인 함수를 cpp에 정의: 클래스 멤버를 헤더에서 선언만 하고 .cpp에 정의했는데, 다른 번역 단위가 그 정의를 못 보는 경우. 템플릿 함수는 정의를 헤더에 두는 것이 원칙입니다.
• static 멤버 변수 정의 누락: 클래스 안의 static int s_count;는 선언일 뿐, 반드시 .cpp에서 int MyClass::s_count = 0;로 한 번 정의해야 합니다. 이걸 빠뜨리면 LNK2019(또는 LNK2001)가 납니다.
• DLL의 dllexport/dllimport 불일치: DLL을 만들 땐 __declspec(dllexport), 쓸 땐 __declspec(dllimport)로 맞춰야 합니다.
• 빌드 캐시 문제: 설정을 다 고쳤는데도 같은 오류가 반복되면, 솔루션 정리(Clean) 후 다시 빌드(Rebuild)해 보세요. 오래된 .obj가 남아 있을 수 있습니다.

6. 요약 체크리스트

• 호출하는 함수의 **정의(구현)**가 실제로 존재하는가
• 정의가 담긴 .cpp가 프로젝트 빌드에 포함됐는가
• 선언과 정의의 시그니처가 완전히 일치하는가
• 필요한 .lib가 추가 종속성과 라이브러리 디렉터리에 등록됐는가
• **플랫폼(x86/x64)·구성(Debug/Release)**이 라이브러리와 일치하는가
• C 라이브러리는 **extern "C"**로 감쌌는가
• static 멤버 변수의 외부 정의를 했는가
• MFC 프로젝트라면 "MFC 사용" 설정과 메시지 맵 핸들러 구현을 확인했는가

LNK2019는 막막해 보이지만, 본질은 "구현체를 어디서도 못 찾았다"는 단순한 신호입니다. 위 순서대로 좁혀가면 거의 항상 원인이 드러납니다.

AI에게 물어볼 때 (프롬프트 팁)

링커 오류는 메시지 한 줄에 많은 단서가 들어 있어, AI에게 질문할 때 데코레이트된 심볼 이름과 환경 정보를 함께 제공하면 정확도가 크게 올라갑니다. ChatGPT나 Claude에게 물어볼 때 다음처럼 구조화해 보세요.

프롬프트 예시 1 — 오류 메시지 전체를 그대로 전달

Visual Studio 2022, C++/MFC, x64 Debug 구성에서 다음 LNK2019가 발생한다.
[오류 메시지 전문 붙여넣기]
이 데코레이트된 심볼 이름을 디맹글링해서 어떤 함수 시그니처인지 알려주고,
원인 후보를 가능성 높은 순서로 정렬한 뒤 각 후보의 점검 방법을 단계로 제시해줘.

프롬프트 예시 2 — 라이브러리 링크 문제 좁히기

외부 SDK(헤더 포함됨)의 함수를 호출하는데 LNK2019가 난다.
이게 .lib 미링크 문제인지, 플랫폼(x86/x64) 불일치인지,
extern "C" 누락인지 구분하려면 무엇을 어떤 순서로 확인해야 하는지
체크리스트 형태로 알려줘. 각 항목마다 Visual Studio의 정확한 설정 경로도 함께.

프롬프트 예시 3 — MFC 특화 진단

MFC 다이얼로그 기반 앱에서 메시지 핸들러 관련 LNK2019가 의심된다.
BEGIN_MESSAGE_MAP에 등록한 핸들러와 실제 멤버 함수 정의가 어긋났을 때의
증상과 점검 포인트를 알려주고, 재발을 막는 코딩 습관도 제안해줘.

이처럼 **환경(컴파일러/플랫폼/구성) + 오류 전문 + 원하는 출력 형식(체크리스트/우선순위)**을 한 번에 명시하면, AI가 추측을 줄이고 바로 실행 가능한 답을 내놓습니다. 좋은 디버깅은 좋은 질문에서 시작합니다 — 이것이 Prompt Architect가 강조하는 프롬프트 설계의 기본 원칙입니다.