🔨 Vue `defineProps`에서 넘긴 prop이 `props`가 아니라 `$attrs`로 빠진 문제

파일 업로드 컴포넌트에 target 값을 넘겨서 업로드 API 요청 시 targetType으로 사용하려고 했다.
부모 컴포넌트에서는 아래처럼 file-input 컴포넌트에 target prop을 추가로 넘기고 있었다.

<file-input
  v-model="salesOrderDetail.fileList"
  :mode="'edit'"
  :target="'ORDER'"
/>

공통 컴포넌트인 file-input.vue에서는 props를 이렇게 선언했다.

const props = withDefaults(defineProps<IFileUploadProps>(), {
  module: "",
  fileCategory: "",
  target: "",
  mode: "edit",
  modelValue: () => [],
  clearable: false,
  multiple: true,
  accept: ".ppt, .pdf, .hwp, .docx, .xls, .xlsx, .png, .jpg, .jpeg",
  maxSize: 10,
  error: false,
  errorMessage: "",
  hintMessage: "",
  placeholder: "파일첨부"
});

그리고 업로드 요청을 보낼 때 이렇게 사용하고 있었다.

await apiClient.file<IFileResponse>("/files/upload", {
  moduleCode: props.module,
  fileType: "FILE",
  targetType: props.target ?? null,
  file
});

그런데 이상하게도 props.target 값이 보이지 않았다.

❓ 처음에는 부모에서 값을 잘못 넘긴 줄 알았다.
그래서 테스트용으로 fileCategory도 추가해서 넘겨봤다. ❓

<file-input
  v-model="salesOrderDetail.fileList"
  :mode="'view'"
  :target="'ORDER'"
  :fileCategory="'abc'"
/>

하지만 여전히 원하는 값이 props에서 확인되지 않았다.

---

원인 찾기

콘솔로 아무리 찍어봐도 보이지 않길래 일단 상위에 v-bind="$attrs"선언해 놓아서 혹시... 몰라`props`와 `$attrs`를 각각 확인했다.

(언제나 항상 혹시가 문제지..?)

const attrs = useAttrs();

console.log("props.target:", props.target);
console.log("attrs.target:", attrs.target);
console.log("attrs:", attrs);

결과는 다음과 같았다.

props.target: undefined
attrs.target: ORDER
attrs: Proxy(Object) { target: 'ORDER' }

여기서 중요한 점은 부모에서 값이 안 넘어온 게 아니라는 것이다.

부모가 넘긴 target="ORDER"는 실제로 자식까지 도착했다.
다만 Vue가 이 값을 props로 인식하지 못해서 $attrs로 넘겨버린 것이다.

즉 문제는 공통 컴포넌트의 defineProps 처리 쪽에 있었다.

---

타입 선언 확인

처음에는 IFileUploadProps 타입에 target이 없는 줄 알았다.

하지만 타입 파일을 확인해보니 target은 분명히 존재했다.

interface IBaseUploadProps<T extends IFileResponse = IFileResponse> {
  modelValue: T[];
  mode?: "edit" | "view";
  required?: boolean;
  hint?: string;
  hintMessage?: string;
  readonly?: boolean;
  disabled?: boolean;
  persistentHint?: boolean;
  clearable?: boolean;
  multiple?: boolean;
  maxSize?: number;
  module: string;
  fileCategory?: string;
  target?: string;
}

export interface IFileUploadProps extends IBaseUploadProps<ISaveFile> {
  placeholder?: string;
  accept?: string;
  target?: string;
}

TypeScript 기준으로는 문제가 없어 보였다.

IFileUploadProps는 IBaseUploadProps<ISaveFile>를 상속하고 있고,
target?: string도 존재한다.

그런데 런타임에서는 props.target이 아니라 $attrs.target으로 빠지고 있었다.

---

진짜 원인

원인은 defineProps<IFileUploadProps>()에 넘긴 타입 구조가 Vue SFC 컴파일러가 런타임 props로 안정적으로 변환하기에는 복잡했던 것이다.
(뭔가 doc에 있어보여서 이용하면 왜 이런게 터지는거죠..?)

문제가 된 구조는 다음 조합이었다.

interface IBaseUploadProps<T extends IFileResponse = IFileResponse> {
  ...
  target?: string;
}

export interface IFileUploadProps extends IBaseUploadProps<ISaveFile> {
  ...
  target?: string;
}

즉,

• imported interface
• extends
• generic
• 중복 선언된 prop

이 조합이 들어가 있었다.

TypeScript는 이 타입을 정상적으로 이해한다.

하지만 Vue의 defineProps<T>()는 완전한 TypeScript 타입 체커처럼 동작하지 않는다.
Vue SFC 컴파일러는 타입 정보를 기반으로 런타임 prop 옵션을 만들어야 하는데, 이 과정은 제한적인 AST 분석에 가깝다.

그래서 TypeScript 입장에서는 target이 존재하지만, Vue 컴파일러가 런타임 props 목록으로 변환하는 과정에서 target을 누락할 수 있다.

그 결과 Vue는 부모에서 전달받은 target을 이렇게 판단한다.

target? 내가 아는 prop 목록에 없네.
그럼 props가 아니라 attrs로 넘긴다.

그래서 최종 결과가 이렇게 된 것이다.

props.target // undefined
attrs.target // "ORDER"

---

해결법

가장 확실한 해결법은 defineProps에 사용하는 타입을 flat하게 만드는 것이다.

즉 extends + generic 구조를 피하고, 해당 컴포넌트에서 사용하는 props를 직접 명시한다.

interface FileInputProps {
  modelValue: ISaveFile[];
  mode?: "edit" | "view";
  required?: boolean;
  hint?: string;
  hintMessage?: string;
  readonly?: boolean;
  disabled?: boolean;
  persistentHint?: boolean;
  clearable?: boolean;
  multiple?: boolean;
  maxSize?: number;
  module: string;
  fileCategory?: string;
  target?: string;
  placeholder?: string;
  accept?: string;
  error?: boolean;
  errorMessage?: string;
}

const props = withDefaults(defineProps<FileInputProps>(), {
  module: "",
  fileCategory: "",
  target: "",
  mode: "edit",
  modelValue: () => [],
  clearable: false,
  multiple: true,
  accept: ".ppt, .pdf, .hwp, .docx, .xls, .xlsx, .png, .jpg, .jpeg",
  maxSize: 10,
  error: false,
  errorMessage: "",
  hintMessage: "",
  placeholder: "파일첨부"
});

이렇게 변경하면 Vue가 target을 정상적으로 prop으로 인식한다.

이후 API 요청에서도 정상적으로 사용할 수 있다.

await apiClient.file<IFileResponse>("/files/upload", {
  moduleCode: props.module,
  fileType: "FILE",
  targetType: props.target || null,
  fileCategory: props.fileCategory || null,
  file
});

여기서 ?? null보다 || null을 사용한 이유는 기본값이 빈 문자열일 수 있기 때문이다.

props.target ?? null

이렇게 쓰면 props.target이 ""일 때 그대로 빈 문자열이 들어간다.

반면,

props.target || null

이렇게 쓰면 빈 문자열일 경우 null로 처리할 수 있다.

---

다른 해결 방법에는...이런게 있대요

공통 타입을 꼭 재사용하고 싶다면 generic을 제거하는 것도 방법이다.

export interface IBaseUploadProps {
  modelValue: ISaveFile[];
  mode?: "edit" | "view";
  required?: boolean;
  hint?: string;
  hintMessage?: string;
  readonly?: boolean;
  disabled?: boolean;
  persistentHint?: boolean;
  clearable?: boolean;
  multiple?: boolean;
  maxSize?: number;
  module: string;
  fileCategory?: string;
  target?: string;
}

export interface IFileUploadProps extends IBaseUploadProps {
  placeholder?: string;
  accept?: string;
  error?: boolean;
  errorMessage?: string;
}

다만 가장 안전한 방법은 defineProps에 들어가는 타입만큼은 최대한 단순하고 명확하게 유지하는 것이다.

---

임시방편

당장 구조를 바꾸기 어렵다면 $attrs에서 값을 꺼내 사용할 수도 있다.

const attrs = useAttrs();

const uploadTarget = computed(() => {
  return props.target || String(attrs.target || "");
});

그리고 업로드 요청에서는 이렇게 사용한다.

await apiClient.file<IFileResponse>("/files/upload", {
  moduleCode: props.module,
  fileType: "FILE",
  targetType: uploadTarget.value || null,
  file
});

하지만 이 방법은 근본적인 해결책은 아니다.

target은 명확히 컴포넌트의 prop으로 사용되는 값이기 때문에 $attrs에서 꺼내 쓰는 것보다 defineProps에서 정상적으로 인식되도록 고치는 것이 맞다.

---

다음에 조심할 것

defineProps<T>()에 타입을 넣을 때는 TypeScript에서 문제가 없다고 해서 Vue 런타임에서도 항상 정상 동작한다고 믿으면 안 된다.

특히 아래와 같은 타입 구조는 조심해야 한다.

interface BaseProps<T> {
  value: T;
}

interface ChildProps extends BaseProps<SomeType> {
  target?: string;
}

이런 구조는 TypeScript에서는 정상이어도 Vue SFC 컴파일러가 런타임 props로 변환하는 과정에서 일부 prop을 누락할 수 있다.

앞으로는 다음 기준을 지키는 것이 좋다.

1. defineProps에 넣는 타입은 최대한 flat하게 작성하기

interface ComponentProps {
  modelValue: SomeType[];
  target?: string;
  mode?: "edit" | "view";
}

2. props가 안 잡히면 $attrs를 바로 확인하기

const attrs = useAttrs();

console.log("props.target:", props.target);
console.log("attrs.target:", attrs.target);

만약 props에는 없고 $attrs에 있다면 부모 전달 문제라기보다 자식의 prop 선언 문제일 가능성이 높다.

3. console.log(props)만 믿지 않기

Vue의 props는 reactive proxy이기 때문에 콘솔에서 펼쳐 보는 것만으로는 헷갈릴 수 있다.

가능하면 개별 값을 직접 찍는 것이 좋다.

console.log("target:", props.target);
console.log("module:", props.module);
console.log("mode:", props.mode);

4. 공통 타입 재사용보다 컴포넌트 안정성을 우선하기

공통 타입을 재사용하면 코드가 깔끔해 보이지만, defineProps에서는 오히려 런타임 변환 문제가 생길 수 있다.

특히 공통 타입이 generic, extends, imported type을 포함하고 있다면 props 선언에는 flat type을 사용하는 것이 더 안전하다.

---

정리

이번 문제는 부모 컴포넌트에서 prop을 잘못 넘긴 문제가 아니었다.

부모에서 넘긴 값은 자식까지 정상적으로 도착했다.
다만 Vue가 해당 값을 prop으로 인식하지 못해서 $attrs로 넘겨버린 것이 문제였다.

핵심 원인은 defineProps<IFileUploadProps>()에 사용한 타입이 extends + generic 구조였고, Vue SFC 컴파일러가 이를 런타임 props로 완전히 변환하지 못한 것이었다.

해결은 defineProps에 사용하는 타입을 flat하게 바꾸는 것.

interface FileInputProps {
  modelValue: ISaveFile[];
  module: string;
  target?: string;
  fileCategory?: string;
  mode?: "edit" | "view";
}

이렇게 단순하게 선언하면 props.target으로 정상 접근할 수 있다.

이번 일을 통해 알게 된 점은 하나다.

TypeScript가 이해하는 타입과 Vue가 런타임 props로 변환할 수 있는 타입은 다를 수 있다.