오류·연결 문제 해결

자주 겪는 문제를 설치 → 연결 → 변환 순으로 정리했습니다. 증상을 찾아 원인과 해결을 확인하세요.

1. 설치

아래 세 오류 모두 설치 플래그·~/.npmrc 설정과 관련됩니다. 기본 설정은 설치를 참고하세요.

401 Unauthorized

• 원인: 인증에 실패했습니다.
• 해결: 아래를 순서대로 확인하세요.
  1. GitHub mildang org 멤버인지 (아니면 어떤 토큰으로도 안 되니 초대부터 받으세요)
  2. classic 토큰인지 (fine-grained 토큰은 지원하지 않습니다)
  3. 토큰 목록에서 Configure SSO → mildang → Authorize를 눌렀는지
  4. 환경변수가 실제로 설정돼 있는지 (echo ${GITHUB_PACKAGES_TOKEN:+설정됨})

404 Not Found

• 원인: npm이 기본 레지스트리(registry.npmjs.org)에서 패키지를 찾고 있습니다.
• 해결: --@mildang:registry=… 플래그를 넣거나 ~/.npmrc에 @mildang:registry 줄을 추가하세요.

Cannot find module … · ERR_MODULE_NOT_FOUND

• 원인: 설치가 온전하지 않습니다.
• 해결: npm i -g @mildang/ids-use@latest로 다시 설치하세요 (설치 단계의 플래그나 ~/.npmrc가 필요합니다).

2. 연결

포트 9222에 연결 실패

• 원인: Figma가 연결 가능한 상태로 켜져 있지 않습니다.
• 해결: ids-use launch로 켜세요 (이미 실행 중이면 자동으로 재시작합니다). 그래도 안 되면 Figma를 ⌘Q로 완전히 종료한 뒤 다시 실행하세요.

명령이 응답 없이 멈춤

• 원인: Figma 탭이 비활성 상태입니다.
• 해결: 파일 탭을 한 번 클릭해 활성화하세요. 그래도 안 되면 Figma를 재시작하세요 (포트는 유지됩니다).

ids-use launch가 "macOS만 지원"

• 원인: ids-use launch는 macOS 전용입니다.
• 해결: Windows·Linux에서는 설치의 OS별 명령으로 Figma를 디버그 포트와 함께 직접 켜세요. 이후 명령은 모두 동일하게 동작합니다.

3. 변환·확인

노드 없음 (선택된 노드 없음)

• 원인: 대상 노드가 지정되지 않았습니다.
• 해결: Figma에서 프레임을 선택하거나 노드 링크를 인자로 넘기세요. 링크의 파일이 열려 있어야 하며, 파일이 여러 개면 --file <fileKey>로 대상을 지정하세요.

render 시간 초과

• 원인: 기본 대기 시간(180초)을 넘겼습니다.
• 해결: 페이지가 크거나 import가 많으면 --timeout 값을 늘리세요 (예: --timeout 600).

경고 0인데 배치 어긋남

• 원인: --dry는 값 전달만 검사하고 레이아웃은 재지 않습니다.
• 해결: 가로로 놓으려면 display="flex", 폭을 정하려면 width·flex를 명시한 뒤 ids-use screenshot으로 확인하세요.

export 후 스타일 어긋남

• 원인: 코드만으로는 스타일을 판단하기 어렵습니다.
• 해결: 스토리북·실물로 확인하고, 그래도 해결되지 않으면 담당자에게 시안을 공유하세요.