남들은 다 되는 유니티 자동완성, 내 visual studio만 안 될 때

유니티에서 C# 스크립트를 더블클릭해 visual studio로 열었는데 코드가 전부 흰 글씨입니다. GameOb까지 쳐도 GameObject가 뜨지 않고, 오타를 내도 빨간 줄은 유니티 콘솔에만 생깁니다. 강의 영상에서는 MonoBehaviour에 색이 들어가 있는데 내 화면만 밋밋합니다.

Visual Studio를 지우고 다시 깔아도 그대로인 경우가 많습니다. 고장 난 것이 프로그램이 아니라 연결이기 때문입니다. 흰 글씨는 Visual Studio가 그 스크립트를 유니티 프로젝트의 일부로 읽지 못했다는 신호입니다.

그렇다면 연결은 어디서 끊겼을까요? 유니티와 Visual Studio 사이에는 이어져야 할 고리가 네 개 있습니다. 유니티 쪽 설정 두 개, 그 결과로 생기는 프로젝트 파일, Visual Studio 쪽 설치 하나입니다. 이 글은 먼저 어느 쪽이 끊겼는지 가르는 법을 보여 드리고, 네 고리를 순서대로 잇습니다. Windows의 Unity 2020 이후 버전과 비주얼 스튜디오 2022를 기준으로 합니다.

visual studio 편집기 왼쪽 위 칸부터 봅니다

코드 창 맨 위, 파일 탭 바로 아래에 드롭다운 세 칸이 있습니다. Microsoft는 이 줄을 탐색 모음이라고 부릅니다. 왼쪽 칸은 지금 파일이 어느 프로젝트에 속해 있는지 보여 줍니다.

정상이라면 여기에 Assembly-CSharp가 보입니다. 유니티가 Assets 폴더의 스크립트를 묶어 만든 프로젝트 이름입니다. Assembly Definition(asmdef)으로 스크립트를 나눠 두었다면 그 asmdef 이름이 보입니다.

흰 글씨인 화면에서는 대개 이 칸에 기타 파일(Miscellaneous Files)이 적혀 있습니다. 어떤 프로젝트에도 속하지 않은 채 열린 파일이라는 뜻입니다. Visual Studio는 이런 파일을 빌드에 넣지 않고, 어떤 라이브러리를 참조하는지도 알지 못합니다. UnityEngine을 모르니 GameObject를 추천할 수도, MonoBehaviour에 색을 입힐 수도 없습니다.

두 번째로 볼 곳은 솔루션 탐색기(Ctrl+Alt+L)입니다. 아예 비어 있는지, 프로젝트 이름 옆에 괄호가 붙어 있는지 확인합니다. 두 화면을 합치면 끊긴 고리가 거의 가려집니다.

보이는 것	끊긴 고리	먼저 볼 곳
왼쪽 위 칸이 기타 파일, 솔루션 탐색기가 비어 있음	유니티가 솔루션을 넘기지 못함	External Script Editor, 패키지
Visual Studio가 안 열리거나 빈 창만 뜸	External Script Editor 또는 패키지	패키지 설치 여부
Assembly-CSharp 옆에 (호환되지 않음)·(언로드됨)	Visual Studio가 프로젝트를 못 읽음	워크로드, 다시 로드
다른 스크립트는 정상인데 이 파일만 기타 파일	파일이 프로젝트 목록에 없음	Regenerate project files
Assembly-CSharp로 열리는데 유니티 함수만 추천이 안 됨	워크로드 또는 Visual Studio 버전	워크로드, 업데이트

한 가지만 기억해 두세요. 이 왼쪽 위 칸은 설정뿐 아니라 파일을 어떻게 열었는지에 따라서도 바뀝니다. 이 이야기는 뒤에서 다시 꺼냅니다.

유니티 쪽 첫 고리: External Script Editor

유니티에서 스크립트를 더블클릭하면 무엇으로 열지는 이 설정 하나가 정합니다. 메뉴는 Edit > Preferences > External Tools > External Script Editor입니다.

여기에 설치한 Visual Studio 이름이 골라져 있어야 합니다. 흔한 함정은 Open by file extension입니다. 유니티 문서에 따르면 이 항목은 Windows가 .cs 파일에 연결해 둔 기본 앱으로 파일을 엽니다. 유니티가 솔루션 정보를 함께 넘기는 것은 Visual Studio처럼 직접 지원하는 편집기를 골랐을 때뿐입니다. 그래서 이 상태로는 Visual Studio가 열려도 파일 하나만 받아 기타 파일이 됩니다.

1. Visual Studio를 닫습니다.
2. External Script Editor 목록에서 Visual Studio가 들어간 항목을 고릅니다.
3. 목록에 없으면 Browse…로 설치 폴더 안의 Common7\IDE\devenv.exe를 지정합니다. 커뮤니티판 2022의 기본 경로는 C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\devenv.exe입니다.
4. 유니티의 Project 창에서 스크립트를 다시 더블클릭해 엽니다.

Visual Studio가 깔려 있는데도 목록에 아예 안 보인다면 이 설정보다 한 칸 앞이 문제입니다. 목록을 채우는 것이 다음 장의 패키지이기 때문입니다.

유니티 쪽 둘째 고리: Visual Studio Editor 패키지와 프로젝트 파일

Unity 2020부터 Visual Studio 연동은 엔진 본체가 아니라 Visual Studio Editor 패키지가 맡습니다. Visual Studio를 찾아 목록에 올리고, Visual Studio가 읽을 .sln과 .csproj 파일을 만드는 것이 이 패키지입니다. 기본으로 들어 있지만, 프로젝트를 옮기거나 패키지를 정리하다 빠지는 일이 있습니다.

패키지가 빠지면 두 가지가 함께 사라집니다. External Script Editor 목록의 Visual Studio, 그리고 그 아래의 Regenerate project files 버튼입니다. 유니티 포럼에는 Unity 6에서 Visual Studio 2026이 목록에 없다가, 이 패키지를 설치하자 바로 고를 수 있게 된 사례가 있습니다.

1. Window > Package Manager를 엽니다.
2. In Project 목록에서 Visual Studio Editor를 찾습니다. 없으면 Unity Registry에서 찾아 Install을 누릅니다.
3. 있으면 버전을 봅니다. Microsoft 지원 표 기준으로 비주얼 스튜디오 2022는 2.0.11 이상이 필요합니다. Update가 보이면 올립니다. 버전이 잠겨 있으면 Version History 탭에서 고릅니다.
4. Preferences > External Tools로 돌아가 Visual Studio를 고르고 Regenerate project files를 누릅니다.

이름이 비슷한 Visual Studio Code Editor는 예전 VS Code용 패키지라 이 일을 대신하지 못합니다. Regenerate project files는 있는 .csproj를 갱신하고 빠진 파일을 새로 만듭니다(Unity 패키지 문서). 버튼 위의 Generate .csproj files 체크 상자는 설치한 패키지 코드용입니다. Assets 폴더의 내 스크립트는 체크 상자와 상관없이 Assembly-CSharp(asmdef를 썼다면 그 프로젝트)에 들어갑니다.

누른 뒤에는 유니티 프로젝트 폴더 맨 위를 열어 봅니다. 프로젝트이름.sln과 Assembly-CSharp.csproj가 보이면 유니티 쪽 고리는 이어진 것입니다. 이제 남은 것은 Visual Studio가 이 파일을 읽을 수 있느냐입니다.

Visual Studio 쪽 고리: 워크로드와 ‘호환되지 않음’

유니티가 파일을 잘 만들어도, 받는 쪽에 유니티 프로젝트를 읽는 도구가 없으면 소용이 없습니다. 그 도구가 Visual Studio Tools for Unity이고, 설치 관리자에서는 Unity를 사용한 게임 개발 워크로드로 들어옵니다. 유니티 허브가 아니라 Visual Studio 홈페이지에서 따로 설치했다면 이 워크로드가 빠져 있기 쉽습니다.

1. Visual Studio Installer를 열고 설치된 버전 옆의 수정을 누릅니다.
2. 워크로드 탭에서 Unity를 사용한 게임 개발(Game development with Unity)을 체크하고 수정을 누릅니다.
3. Visual Studio를 다시 열 때 유니티 대상 프레임워크를 내려받으라는 안내가 뜨면, 같은 설치 관리자의 개별 구성 요소 > .NET에서 4.x 대상 지정 팩(4.7.1 등)을 설치합니다.
4. 도움말 > 업데이트 확인으로 Visual Studio를 최신으로 올립니다. Microsoft는 IntelliSense와 코드 색 문제에 최신 버전 업데이트를 먼저 권합니다.

워크로드를 깔았는데도 솔루션 탐색기에 Assembly-CSharp (호환되지 않음)이나 (언로드됨)이 남아 있을 수 있습니다. 이유가 따로 있습니다. Visual Studio는 한 번 ‘호환되지 않음’으로 본 프로젝트를 그 상태로 기억합니다. 원인을 고친 뒤에도 사용자가 직접 다시 로드하기 전에는 다시 읽지 않습니다.

그래서 앞의 단계를 하나 할 때마다 해당 프로젝트를 마우스 오른쪽 버튼으로 눌러 다시 로드(Reload Project)를 고릅니다. 이걸 빼먹으면 이미 고친 원인을 두고 다음 단계로 넘어가게 됩니다.

연결이 끊기는 곳: 파일이 아니라 프로젝트입니다

앞에서 왼쪽 위 칸이 파일을 어떻게 열었는지에 따라서도 바뀐다고 했습니다. 네 고리를 모두 이어도, Windows 탐색기에서 .cs 파일을 더블클릭하거나 Visual Studio의 최근 파일 목록에서 스크립트를 열면 솔루션 없이 파일만 열립니다. 결과는 다시 기타 파일입니다. 설정은 다 맞는데 가끔만 흰 글씨가 된다면 대부분 여기입니다.

지금까지 본 네 고리는 결국 한 가지를 위해 있습니다. 유니티는 프로젝트 파일을 만들어 넘기고, Visual Studio는 그 프로젝트를 읽어 스크립트가 어디에 속하는지 압니다. 남들 화면에서 자동완성이 되는 것도 Visual Studio가 특별해서가 아니라 이 프로젝트가 제대로 열려 있어서입니다.

자동완성은 스크립트 파일이 아니라, 유니티가 만든 프로젝트를 Visual Studio가 읽을 때 켜집니다.

그러니 스크립트는 늘 유니티에서 엽니다. Project 창에서 더블클릭하거나, 메뉴의 Assets > Open C# Project로 솔루션째 엽니다. 이미 Visual Studio가 떠 있다면 탐색기 대신 솔루션 탐색기에서 파일을 고릅니다.

그래도 흰 글씨라면: 프로젝트 파일을 지우고 다시 만듭니다

Visual Studio 버전을 바꿨거나 다른 PC에서 작업하던 프로젝트를 가져왔다면, 남아 있는 옛 프로젝트 파일이 걸림돌이 되기도 합니다. 이 파일들은 유니티가 언제든 다시 만들기 때문에 지워도 작업물은 그대로입니다. Microsoft 문제 해결 문서도 같은 순서를 권합니다.

1. Visual Studio와 유니티를 모두 닫습니다.
2. 유니티 프로젝트 폴더 맨 위에서 *.sln, *.csproj, 숨김 폴더 .vs를 지웁니다. 패키지 2.0.24 이후에 Visual Studio 2026을 쓰면 솔루션이 .slnx로 생기니 그것도 지웁니다. Assets, Packages, ProjectSettings 폴더는 건드리지 않습니다.
3. 유니티로 프로젝트를 열고 Assets > Open C# Project를 누릅니다.
4. 솔루션 탐색기에 (호환되지 않음)이 보이면 다시 로드를 누릅니다.

Library 폴더까지 지우라는 조언도 보이지만, Microsoft 문서에서 그 단계는 중단점이 안 걸릴 때의 처방입니다. 자동완성 문제라면 위 세 가지로 충분하고, Library를 지우면 다음 실행 때 에셋 가져오기를 처음부터 다시 하느라 오래 걸립니다.

이어졌는지는 네 가지로 확인합니다.

• 왼쪽 위 칸에 기타 파일 대신 Assembly-CSharp가 보입니다.
• GameOb까지 치면 GameObject가 목록에 뜹니다.
• using UnityEngine.SceneManagement; 없이 SceneManager를 쓰면 Visual Studio에도 빨간 줄이 생깁니다.
• 도구 모음의 실행 버튼이 보통 ‘Unity에 연결’로 표시됩니다.

여기까지 해도 안 된다면 Microsoft의 Visual Studio Tools for Unity 문제 해결 문서가 다음 순서를 이어 줍니다. MEF 캐시 지우기, Unity 워크로드만으로 Visual Studio 다시 설치하기, 확장 관리에서 다른 확장 끄기입니다. 재설치는 이 목록에서도 거의 마지막 단계입니다.

흰 글씨를 만나면 재설치보다 왼쪽 위 칸부터 보세요. 자동완성은 파일이 아니라 프로젝트에서 나옵니다.