Nuxt.js 프로젝트에서 로컬 파일 시스템(예: 텍스트 파일, 이미지, JSON 등)에 접근하는 방법

Nuxt.js 프로젝트에서 로컬 파일 시스템(예: 텍스트 파일, 이미지, JSON 등)에 접근하는 방법을 묻는 것으로 이해했습니다. Nuxt는 기본적으로 Node.js 기반의 서버 사이드 렌더링(SSR) 프레임워크이므로, 로컬 파일 접근은 주로 서버 측 코드에서 이루어집니다. 아래에 이를 상세히 블로그글 스타일로 설명드릴게요.

---

Nuxt.js에서 로컬 파일 접근: 방법과 주의사항

안녕하세요, Nuxt.js 개발자 여러분! 오늘은 Nuxt.js 프로젝트에서 로컬 파일(예: JSON, 텍스트, 이미지 등)에 접근하는 방법을 알아보겠습니다. Nuxt는 클라이언트와 서버 환경이 공존하는 프레임워크라서, 파일 접근 방식이 일반적인 프론트엔드와는 조금 다를 수 있습니다. 이 글에서는 서버 측에서 파일을 읽는 방법, 정적 파일을 활용하는 방법, 그리고 주의할 점을 상세히 다뤄보겠습니다.

1. Nuxt.js에서 로컬 파일 접근의 기본 이해

Nuxt.js는 두 가지 주요 실행 환경을 제공합니다:

• 클라이언트 측: 브라우저에서 실행되는 코드로, 파일 시스템에 직접 접근할 수 없습니다.
• 서버 측: Node.js로 실행되며, 파일 시스템에 접근할 수 있습니다.

따라서 로컬 파일에 접근하려면 서버 측 코드(예: API 엔드포인트, 서버 미들웨어)나 정적 파일 디렉토리를 활용해야 합니다. 브라우저 환경에서는 보안 정책상 파일 시스템에 직접 접근할 수 없다는 점을 먼저 기억하세요.

 

 

 

2. 방법 1: 서버 측에서 파일 읽기 (Node.js fs 모듈 사용)

Nuxt에서 로컬 파일을 읽으려면 Node.js의 fs (File System) 모듈을 사용하는 것이 가장 일반적입니다. 이를 위해 서버 미들웨어나 API 라우트를 작성해야 합니다.

2.1. 프로젝트 구조 예시

 

my-nuxt-project/
├── pages/
│   └── index.vue
├── server/
│   └── api/
│       └── readFile.js
├── static/
└── nuxt.config.js

2.2. 서버 API 작성

Nuxt는 server/api 디렉토리(기본적으로 @nuxt/nitro 기반)를 통해 서버 엔드포인트를 쉽게 추가할 수 있습니다. 예를 들어, server/api/readFile.js 파일을 만들어 로컬 파일을 읽어보겠습니다.

 

import fs from 'fs/promises';
import path from 'path';

export default defineEventHandler(async (event) => {
  try {
    // 프로젝트 루트의 data.txt 파일 경로
    const filePath = path.resolve(process.cwd(), 'data.txt');
    const fileContent = await fs.readFile(filePath, 'utf-8');
    return { content: fileContent };
  } catch (error) {
    return { error: '파일을 읽는 데 실패했습니다.', details: error.message };
  }
});

• fs/promises: 비동기 파일 읽기를 위한 Node.js 모듈.
• path.resolve: 프로젝트 루트 기준으로 절대 경로를 생성.
• process.cwd(): 현재 작업 디렉토리(프로젝트 루트).

2.3. 프론트엔드에서 API 호출

pages/index.vue에서 위 API를 호출해 파일 내용을 표시합니다:

 

<template>
  <div>
    <h1>로컬 파일 내용</h1>
    <p>{{ fileContent }}</p>
    <button @click="fetchFile">파일 읽기</button>
  </div>
</template>

<script setup>
import { ref } from 'vue';

const fileContent = ref('');

const fetchFile = async () => {
  const response = await $fetch('/api/readFile');
  if (response.content) {
    fileContent.value = response.content;
  } else {
    console.error(response.error);
  }
};
</script>

• $fetch: Nuxt에서 제공하는 기본 HTTP 클라이언트.
• /api/readFile: 서버에서 정의한 엔드포인트.

2.4. 실행

1. 프로젝트 루트에 data.txt 파일을 만들고 내용을 입력합니다(예: "Hello, Nuxt!").
2. npm run dev로 개발 서버를 실행합니다.
3. 브라우저에서 버튼을 클릭하면 data.txt 내용이 표시됩니다.

 

 

728x90

 

3. 방법 2: 정적 파일 활용 (static/ 디렉토리)

Nuxt의 static/ 디렉토리는 빌드 시 정적 자원으로 제공되며, URL로 직접 접근할 수 있습니다. 이 방법은 서버 측 코드 없이 간단히 파일을 사용할 때 유용합니다.

3.1. 정적 파일 준비

 

my-nuxt-project/
├── static/
│   └── data.json
├── pages/
│   └── index.vue

static/data.json에 예시 데이터를 넣습니다:

{
  "message": "Hello from static file!"
}

3.2. 프론트엔드에서 접근

pages/index.vue에서 정적 파일을 가져옵니다:

 

<template>
  <div>
    <h1>정적 파일 내용</h1>
    <p>{{ data.message }}</p>
  </div>
</template>

<script setup>
import { ref, onMounted } from 'vue';

const data = ref({});

onMounted(async () => {
  const response = await fetch('/data.json');
  data.value = await response.json();
});
</script>

• /data.json: static/ 디렉토리의 파일은 루트 URL로 바로 접근 가능.
• fetch: 브라우저에서 정적 파일을 요청.

3.3. 장점과 한계

• 장점: 서버 코드 없이 간단히 사용 가능.
• 한계: 동적 파일 읽기(예: 파일 목록 조회)는 불가능하며, 정적 파일만 지원.

4. 주의사항

Nuxt에서 로컬 파일 접근 시 몇 가지 주의할 점이 있습니다.

4.1. 클라이언트 vs 서버 환경

• 클라이언트 측 코드(<script> 태그 안의 로직)에서는 fs를 사용할 수 없습니다. fs는 Node.js 모듈이므로 서버에서만 동작합니다.
• process.client와 process.server를 사용해 환경을 구분하세요:

  if (process.server) {
    // 서버에서만 실행
    const fs = require('fs');
  }

4.2. 배포 시 경로 문제

• 로컬 파일 경로는 개발 환경(npm run dev)과 빌드 후 배포 환경(npm run generate 또는 SSR 배포)에서 다를 수 있습니다. path.resolve로 절대 경로를 사용하는 것이 안전합니다.
• 정적 파일은 static/에 넣고, 동적 파일은 서버 로직에서 관리하세요.

4.3. 보안

• 로컬 파일을 읽는 API를 공개할 경우, 사용자가 임의의 파일에 접근하지 못하도록 경로를 제한해야 합니다(예: path.normalize로 경로 조작 방지).

5. 추가 팁: Nuxt 모듈과 플러그인

파일 접근을 자주 사용한다면, Nuxt 모듈이나 플러그인을 만들어 재사용성을 높일 수 있습니다. 예를 들어:

• plugins/fileReader.js에서 공통 로직을 정의하고, nuxt.config.js에 등록.
• @nuxt/content 모듈을 사용해 Markdown이나 JSON 파일을 쉽게 관리.

마무리

Nuxt.js에서 로컬 파일 접근은 서버 측(fs와 API)과 정적 파일(static/) 두 가지 방식으로 가능합니다. 프로젝트 요구사항에 따라 동적 파일 읽기냐, 단순 정적 자원 제공이냐를 선택하세요. 서버 환경을 활용하면 더 유연한 작업이 가능하니, Node.js의 강점을 잘 활용해보세요. 질문이 더 있다면 언제든 물어보세요!

---