Next.js 16 + Turbopack + SCSS Alias가 Windows에서 동작하지 않는 문제

WSL Ubuntu에서 잘 되던 프로젝트를 Windows로 옮겼더니 SCSS 빌드 에러가 발생했다.
삽질 끝에 알고 보니 내 코드 잘못이 아닌 Vercel 측 공식 버그였다.

---

발생 환경

• Next.js: 16.0.7 (Turbopack)
• sass: ^1.93.3
• OS: Windows (WSL Ubuntu에서 이전)

---

에러 증상

yarn dev 실행 후 localhost:3000에서 다음과 같은 빌드 에러 발생:

./src/app/(main)/page.module.scss
Error evaluating Node.js code
Error: Can't find stylesheet to import.
  ╷
3 │ @forward './utils';
  │ ^^^^^^^^^^^^^^^^^^
  ╵
  src\shared\styles\mixins\index.scss 3:1  @use
  src\app\(main)\page.module.scss 1:1      root stylesheet

SCSS 파일 구조는 다음과 같았다.

src/shared/styles/mixins/
├── index.scss   ← @forward './utils' 등을 통합
├── _utils.scss
├── _flex.scss
├── _size.scss
├── _spacing.scss
└── _font.scss

// mixins/index.scss
@forward './utils';
@forward './flex';
@forward './size';
@forward './spacing';
@forward './font';

---

삽질 과정

1. alias 경로 오타 발견

next.config.ts를 확인하니 alias 경로가 틀려 있었음

// ❌ 잘못된 경로
turbopack: {
  resolveAlias: {
    '@styles': path.join(__dirname, 'src/styles'), // 존재하지 않는 경로
  },
},

실제 파일은 src/shared/styles에 있었으므로 수정

// ✅ 수정된 경로
turbopack: {
  resolveAlias: {
    '@styles': path.join(__dirname, 'src/shared/styles'),
  },
},

그래도 에러는 계속됐다. 그리고 그러면 왜 wsl에서는 문제가 없었던거니??

2. sassOptions.includePaths 추가 시도

sassOptions: {
  includePaths: [path.join(__dirname, 'src/shared/styles')],
},

효과 없음...

3. sass importer 추가 시도 (findFileUrl)

sassOptions: {
  importers: [{
    findFileUrl(url: string) {
      if (!url.startsWith('@shared')) return null;
      return new URL('file:///' + path.join(__dirname, 'src', url.replace('@', '')));
    },
  }],
},

새로운 에러 발생;;

Error: An importer must have either canonicalize and load methods, or a findFileUrl method.

Turbopack은 findFileUrl 방식의 importer를 지원하지 않는다.

4. canonicalize + load 방식으로 변경 시도

sassOptions: {
  importers: [{
    canonicalize(url: string) { ... },
    load(canonicalUrl: URL) { ... },
  }],
},

역시 동작하지 않았다.

이외에도 스타일시트를 import하는 경로 전부를 상대경로 및 절대경로 방식으로 바꿨다가... 이것도 제대로 안 먹혀서 싹 되돌렸다.

---

찾아낸 원인

핵심 원인은 Next.js 16 Turbopack의 Windows SCSS 경로 처리 버그였다.

환경	경로 구분자	결과
WSL Ubuntu	/ (슬래시)	✅ 정상 동작
Windows	\ (백슬래시)	❌ SCSS @use/@forward 경로 해석 실패

이는 Vercel 공식 GitHub 이슈로 등록된 버그다. 내 코드 잘못이 아니다! ㅜㅜ

그리고 sassOptions가 동작하지 않은 이유도 따로 있었다.

Turbopack은 Rust 기반 아키텍처라 sassOptions로 전달되는 JavaScript 함수를 직접 실행할 수 없다고 한다. findFileUrl, canonicalize, load 등 모든 JavaScript importer 방식이 Turbopack에서는 동작하지 않는다.

---

해결 방법

로컬 개발 (Windows): --webpack 플래그 사용

// package.json
{
  "scripts": {
    "dev": "next dev --webpack",
    "build": "next build"
  }
}

• dev는 Webpack으로 실행 → SCSS alias 정상 동작
• build는 Turbopack 유지 → 배포 시 그대로 사용

배포 (Vercel): 그대로 사용

Vercel 배포 서버는 Linux이므로 Turbopack + SCSS alias가 정상 동작한다. next build에 별도 설정이 필요 없다.

---

정리

상황	명령어	비고
로컬 개발 (Windows)	next dev --webpack	Webpack으로 SCSS 정상 처리
로컬 개발 (WSL/Mac)	next dev	Turbopack 그대로 사용
프로덕션 빌드	next build	Turbopack 유지, Vercel Linux에서 정상 동작

Vercel이 Windows 경로 버그를 픽스하면 package.json에서 --webpack 플래그만 제거하면 된다.

---

참고

• Next.js GitHub Issue #87243