CSS module not found, .module.css, 대소문자 | 맥에서는 되고 리눅스 CI만 실패하면?
맥에서 되고 리눅스 통합 환경만 CSS 모듈을 못 찾으면 import 경로와 파일명 대소문자가 다른 상태다. git ls-files로 실제 이름을 보고 git mv로 맞춘다. Next.js .module.css, webpack Module not found, 깃 core.ignoreCase, 깃허브 액션, 프론트엔드, 개발자 기준. 2026년 9월 Next.js·webpack·깃 공식 문서.
맥에서 되고 리눅스 통합 환경만 CSS 모듈을 못 찾으면, 스타일 파일이 없어서가 아니라 import 경로와 디스크에 있는 파일명의 대소문자가 다릅니다. 맥 기본 디스크는 Button.module.css와 button.module.css를 같은 파일로 열고, 깃허브 액션 우분투는 한 글자라도 다르면 모듈을 못 찾는 줄을 냅니다.
넥스트 빌드가 제 맥에선 초록인데 액션만 빨간 줄이면, 패키지를 다시 깔기 전에 그 불러오기 한 줄과 깃이 추적하는 이름을 나란히 보세요. 노드가 패키지 폴더를 못 찾는 줄과는 칸이 다릅니다.
import 한 줄과 파일명을 한 글자까지 맞춰 보세요. 로컬 next dev는 통과하고 깃허브 액션이나 버셀 빌드만 Module not found: Can't resolve './Button.module.css'를 내면, 거의 이 칸입니다.
한국에서 맥으로 짜고 우분투 러너에 올리는 1인 넥스트 작업에서 자주 납니다. 제가 돌리는 사이트도 컴포넌트 이름을 바꾸다 스타일 파일만 소문자로 남긴 채 커밋한 적이 있습니다. 맥에선 화면이 그대로였고, 액션 로그에만 그 상대 경로가 찍혔습니다. 점심시간에 패키지를 지워 다시 깔고, 노드 버전까지 맞췄는데도 같은 줄이었습니다.
패키지를 지워 다시 깔거나 노드 버전을 맞추기 전에, 에러에 나온 경로 문자열을 복사해 저장소에서 찾으세요. 파일이 보이면 없는 게 아닙니다. 이름 철자의 대소문자만 다른 겁니다. 탐색기에서 파일이 보여도 안심하지 마세요. 맥 탐색기는 느슨한 이름도 같은 아이콘으로 엽니다.
증상
먼저 볼 곳
아닌 칸
맥 초록, 우분투 액션만 실패
import 경로와 git ls-files 이름
node_modules 재설치
Can't resolve './….module.css'
그 상대 경로 한 줄
넥스트 설정 전체
폴더까지 못 찾음
components vs Components
CSS 문법
고쳤는데 액션이 예전 이름
깃이 대소문자 변경을 삼킴
캐시 삭제만
먼저 기억할 것 | 맥에서 파일이 열리면 디스크에 있는 겁니다. 리눅스만 거절하면 경로 문자열이 파일명과 다릅니다. 없는 파일을 찾는 줄과 섞지 마세요.
에러 줄이 가리키는 파일 이름
에러에 찍힌 상대 경로가 디스크 이름과 같은지부터 봅니다. 넥스트는 CSS 모듈을 웹팩(또는 터보팩)으로 해석하고, 못 찾으면 Module not found 메시지를 냅니다. 줄 안의 Can't resolve './Button.module.css'가 범인 이름입니다.
그 문자열은 컴포넌트 파일이 있는 폴더 기준입니다. app/blog/page.js에서 ./blog.module.css를 부르면 app/blog/blog.module.css를 찾습니다. 넥스트 문서도 확장자가 .module.css인 파일만 지역 클래스로 묶는다고 적습니다.
별칭 @/를 써도 풀고 난 뒤 남은 경로의 대소문자는 그대로입니다. @/components/Button.module.css가 디스크의 components/button.module.css를 가리키면, 맥은 통과하고 리눅스는 거절합니다. 별칭 설정과 자리를 나누고, 풀린 경로 한 줄만 봅니다.
에러 경로와 디스크 이름을 같이 보기
# 저장소에서 실제 추적 이름 보기 (대소문자 그대로)
git ls-files | grep -i 'button.module.css'
# 예시
# components/button.module.css ← 디스크·깃 이름
# 코드: import styles from './Button.module.css' ← 리눅스에서 실패
맥은 같은 파일로 열고, 리눅스 러너는 한 글자라도 다르면 거절한다
맥 디스크가 대소문자를 느슨히 보는 이유
맥 기본 디스크는 대소문자를 구분하지 않습니다. APFS를 기본값으로 쓰면 Button.module.css를 소문자로 불러도 파일이 열립니다. 깃허브 호스티드 러너의 우분투는 구분해서, 같은 커밋이 액션에서만 깨집니다.
윈도우도 기본 NTFS는 대소문자를 느슨히 봅니다. 그래서 집 노트북 두 대가 통과하고, 리눅스 빌드만 빨간 줄인 그림이 흔합니다. 버셀 빌드 이미지도 리눅스라 로컬 맥과 갈립니다.
고치는 쪽은 코드입니다. 디스크를 대소문자 구분 포맷으로 다시 까는 일은 이 에러의 답이 아닙니다. import 문자열을 깃이 추적하는 이름과 같게 맞추면 맥과 리눅스가 같은 파일을 엽니다. 팀원이 윈도우고 나는 맥이면 둘 다 통과해서 더 늦게 들킵니다. 리눅스 빌드가 첫 심사관입니다.
환경
파일명 대소문자
그래서
맥 기본 APFS
구분 안 함
잘못된 import도 로컬에선 열림
윈도우 기본 NTFS
구분 안 함
맥과 같이 통과하기 쉬움
우분투 액션 · 버셀
구분함
한 글자 다르면 모듈을 못 찾음
깃 core.ignoreCase
맥에서 흔히 true
이름만 바꾼 커밋이 안 잡힘
깃이 이름만 바꾼 커밋을 삼키는 경우
깃은 대소문자만 바꾼 이름을 커밋하지 않을 수 있습니다. 맥에서 core.ignoreCase가 true이면, 탐색기에서 button.module.css를 Button.module.css로 고쳐도 인덱스가 예전 이름을 유지합니다. 로컬은 새 이름으로 열리고, 원격·리눅스는 예전 이름을 받습니다.
깃 설정 문서의 core.ignoreCase가 그 스위치입니다. 값을 함부로 false로 바꾸기보다, 이름 변경은 git mv로 기록하세요. 한 번에 안 되면 임시 이름으로 옮겼다가 원하는 이름으로 되돌립니다.
커밋 전에 git ls-files와 코드의 import가 같은지 한 번 더 보세요. 작업 트리에선 고쳐 보여도 인덱스가 안 바뀌면 액션은 예전 파일을 받습니다. 상태 화면에 변경이 안 뜨면 탐색기에서 고친 것뿐입니다. 그때는 임시 이름으로 한 번 옮기는 절차가 필요합니다.
대소문자만 다른 이름을 깃에 기록하기
# 한 번에 안 되면 임시 이름을 거친다
git mv components/button.module.css components/button.module.css.tmp
git mv components/button.module.css.tmp components/Button.module.css
git status
# 코드 import도 ./Button.module.css 로 맞춘 뒤 커밋
탐색기에서 이름을 바꿔도 깃 인덱스는 예전 철자를 들고 있을 수 있다
import를 파일에 맞추는 순서
디스크 이름에 import를 맞추거나, git mv로 파일명을 고칩니다. 둘 중 하나를 고르면 됩니다. 코드를 고치는 쪽이 더 짧을 때가 많습니다.
순서는 이렇습니다. 에러 경로를 복사하고, git ls-files로 실제 이름을 확인하고, import 문자열을 그 이름과 같게 고칩니다. 파일 이름을 컴포넌트와 맞추고 싶다면 git mv로 디스크를 옮긴 뒤 import도 따라갑니다. 폴더가 Components인데 코드가 components를 부르면 파일만 고쳐선 안 됩니다. 같은 커밋에 파일과 폴더가 같이 어긋난 경우도 있어서, 경로를 앞에서부터 한 칸씩 읽는 편이 빠릅니다.
고친 뒤 맥에서만 다시 빌드하지 마세요. 액션이 우분투면 그 잡이 초록이 되어야 끝난 겁니다. 로컬에서 리눅스를 재현하려면 대소문자를 구분하는 볼륨이나 컨테이너에서 같은 import를 열어 보면 됩니다. 혼자 올리는 프리뷰라도 리눅스 빌드 로그의 첫 빨간 줄이 기준입니다. 맥 화면이 예쁘다고 끝난 게 아닙니다.
디스크 이름에 import를 맞추기
// 깃이 추적하는 이름이 button.module.css 이면
import styles from './button.module.css'
export default function Card() {
return <article className={styles.card}>…</article>
}
[ ] 에러의 Can't resolve 경로를 그대로 복사했다
[ ] git ls-files 에 찍힌 이름과 한 글자까지 비교했다
[ ] import 또는 git mv 둘 중 하나로 이름을 맞췄다
[ ] 폴더 이름(components)도 같이 봤다
[ ] 우분투 액션 빌드가 초록인지 확인했다
.module.css와 전역 파일은 다른 칸
.module.css만 지역 클래스로 묶입니다. 전역 파일과 섞지 마세요. 넥스트는 확장자가 .module.css일 때만 CSS 모듈로 취급합니다. button.css를 import styles from './button.css'로 부르면 모듈 객체가 아니라 전역 시트로 들어갑니다.
그건 대소문자 에러가 아닙니다. 클래스가 전역으로 새거나, 모듈처럼 styles.card를 읽다 값이 비는 쪽에 가깝습니다. 사스는 .module.scss가 같은 규칙입니다. 확장자 칸과 경로 대소문자 칸을 한 번에 고치지 마세요.
노드가 node_modules에서 패키지 이름을 못 찾는 줄은 Cannot find module입니다. 스크립트 경로 문자열 자체는 ENOENT입니다. 빌드 스크립트가 다른 이유로 죽은 뒤 npm이 감싼 줄은 ELIFECYCLE입니다. 스타일 파일 경로의 대소문자만 이 증상과 맞춰 보면 됩니다.
확장자를 먼저 보지 말 것 | 맥은 되고 리눅스만 깨지면 확장자보다 철자입니다. .module.css인데도 못 찾으면 이름이 다른 겁니다.
import 경로와 git ls-files 이름을 한 글자까지 비교하세요. 맥 기본 디스크는 대소문자를 구분하지 않아 잘못된 철자도 파일을 엽니다. 우분투 러너는 거절합니다.
탐색기에서 파일명을 고쳤는데도 액션이 예전 이름을 찾습니다.
깃 인덱스가 안 바뀐 겁니다. git mv로 임시 이름을 거쳤다가 원하는 이름으로 옮기세요. git ls-files에 새 철자가 보여야 원격도 따라갑니다.
파일은 맞는데 폴더 이름만 다른 것 같습니다.
components와 Components도 같은 함정입니다. 리눅스는 폴더 철자까지 맞춥니다. 에러 경로의 디렉터리 구간을 ls-files와 같이 보세요.
Cannot find module이랑 같은 줄인가요?
다릅니다. 패키지 이름을 node_modules에서 못 찾는 줄은 다른 글입니다. 여기서는 컴포넌트 옆의 .module.css 상대 경로만 봅니다.
사스 .module.scss도 같이 깨집니다.
같은 규칙입니다. 확장자가 모듈이어도 경로 철자가 다르면 리눅스에서 못 찾습니다. import와 깃 이름을 맞추면 됩니다.
@/ 별칭을 쓰면 대소문자를 안 봐도 되나요?
별칭은 앞부분만 바꿉니다. 풀린 뒤 남은 components/Button.module.css 철자는 그대로 디스크와 비교됩니다. 별칭 설정과 이 에러를 한 칸으로 묶지 마세요.
맥은 되고 리눅스만 CSS 모듈을 못 찾으면 import 경로와 파일명 대소문자를 맞추면 됩니다. git ls-files로 실제 이름을 보고, 코드나 git mv 중 하나로 고친 뒤 우분투 액션이 초록인지 확인하세요. 관련 글: 패키지 모듈, ENOENT, ELIFECYCLE.
CSS modulemodule.css대소문자Module not foundNext.jswebpack깃허브 액션맥리눅스프론트엔드개발자git mv
