Version: 2020.2
WebGL 플레이어 설정
WebGL: Compressed builds and server configuration

WebGL 프로젝트 빌드 및 실행

The Build folder contains the following files ([ExampleBuild] represents the name of the target build folder):

File name Contains
[ExampleBuild].loader.js The JavaScript code that the web page needs in order to load the Unity content.
[ExampleBuild].framework.js JavaScript runtime and plugins.
[ExampleBuild].wasm WebAssembly binary.
[ExampleBuild].mem A binary image to initialize the heap memory for your Player. Unity only generates this file for multi-threaded WebAssembly builds.
[ExampleBuild].data Asset data and Scenes.
[ExampleBuild].symbols.json Debug symbol names necessary to demangle an error stack trace. This file is only generated for Release builds when you enable the Debug Symbols option (File > Build Settings > Player Settings.)
[ExampleBuild].jpg A background image, which displays while the build is loading. This file is only generated when a Background Image is provided in the Player Settings (File > Build Settings > Player Settings > Splash Image). See the Splash Screen page for further information.

If you enable a Compression Method for your build, Unity identifies the extension that corresponds with the compression method and adds this extension to the names of the files inside the Build subfolder. If you enable Decompression Fallback, Unity appends the extension .unityweb to the build file names. Otherwise, Unity appends the extension .gz for the Gzip compression method, or .br for the Brotli compression method. For more information, see WebGL: Compressed builds and server configuration.

If you enable Name Files As Hashes (in the Player Settings), Unity uses the hash of the file content instead of the default filename. This applies to each file in the build folder. This option allows you to upload updated versions of the game builds into the same folder on the server, and only upload the files which have changed between build iterations.

The best way to view the WebGL Player locally is to use Unity’s Build And Run option (menu: File > Build And Run). Unity uses a local web server to host your build, and opens it from a localhost URL. Alternatively, you can use a custom local web server with properly configured response headers. For more information on setting up response headers, see WebGL: Compressed builds and server configuration.

Note: Opening a Player directly from the file system might not work in some browsers. This is due to security restrictions applied to local file URLs.

빌드 설정(Build Settings)

WebGL 빌드 설정에 액세스하려면 빌드 설정 창(File > Build Settings)을 열고 Platform 리스트에서 WebGL 을 선택하십시오.

Build Settings Window
Build Settings Window

개발 빌드

Development Build 설정을 선택하면 Unity는 프로파일러를 지원하는 개발 빌드와 애플리케이션의 오류를 확인할 수 있는 개발 콘솔을 생성합니다. 또한 개발 빌드는 콘텐츠를 축소하지 않습니다. 개발 빌드의 JavaScript는 사람이 읽을 수 있는 포맷이고, Unity는 오류에 대한 스택 추적을 볼 수 있도록 함수 이름을 유지합니다. 하지만 이 경우 개발 빌드가 너무 커져서 배포가 불가능할 수 있습니다. 개발 빌드 설정을 활성화한 경우 Autoconnect ProfilerDeep Profiling Support 만 선택할 수 있습니다.

프로파일러 자동 연결

Unity WebGL 콘텐츠를 프로파일링하려면 Autoconnect Profiler 설정을 선택하십시오. WebGL의 경우 프로파일러를 다른 플랫폼에서 실행 중인 빌드에 연결할 수 없으므로, 이 옵션을 사용하여 콘텐츠를 에디터에 연결해야 합니다. 프로파일러 연결은 WebGL의 WebSocket을 사용하여 처리되지만 웹 브라우저는 콘텐츠에서 발신 연결만 허용하기 때문입니다.

세부 프로파일링 지원

Deep Profiling Support 설정을 활성화하면 Unity 프로파일러가 애플리케이션의 모든 함수 호출을 프로파일링합니다. 자세한 내용은 세부 프로파일링 문서를 참조하십시오.

Player settings

WebGL은 플레이어 설정(메뉴: Edit > Project Settings 에서 Player 카테고리 선택)에 몇 가지 추가 옵션이 있습니다.

기타 설정

엔진 코드 스트립

Other Settings 를 열어 Strip Engine Code 옵션에 액세스합니다. 이 옵션은 기본적으로 선택되어 있어 WebGL에 대해 코드 스트리핑을 활성화합니다. 이 옵션이 선택되어 있으면 Unity는 사용되지 않은 클래스에 대한 코드를 포함시키지 않습니다. 예를 들어, 물리 컴포넌트 또는 함수를 사용하지 않으면 전체 물리 엔진이 빌드에서 제거됩니다. 세부 정보는 아래의 스크리핑 섹션을 참조하십시오.

퍼블리싱 설정

예외 활성화

Publishing Settings 를 열어 Enable Exceptions 에 접근합니다. Enable Exceptions 를 통해 런타임에 예기치 않은 코드 동작(일반적으로 오류로 간주됨)을 처리하는 방법을 지정할 수 있습니다. 다음 옵션이 있습니다.

  • None: 예외 지원이 필요하지 않은 경우에 선택합니다. 성능이 극대화되고 빌드가 최소화됩니다. 이 옵션을 선택하면 폐기된 예외로 인해 해당 설정에 오류가 있는 경우 콘텐츠가 중지됩니다.
  • Explicitly Thrown Exceptions Only (기본): 스크립트의 throw 문에서 명시적으로 지정된 예외를 캡처하고 finally 블록이 호출되도록 하려면 이 옵션을 선택합니다. 이 옵션을 선택하면 스크립트에서 생성된 JavaScript 코드가 더 길어지고 더 느려지지만, 스크립트가 프로젝트의 중요한 병목 지점인 경우를 제외하고는 문제가 되지 않을 것입니다.
  • Full Without Stacktrace: 다음을 캡처하려면 이 옵션을 선택합니다.
    • 스크립트의 throw 문에서 명시적으로 지정된 예외(Explicitly Thrown Exceptions Only 옵션과 동일)
    • Null 레퍼런스
    • 범위 이탈 배열 액세스
  • Full With Stacktrace: 이 옵션의 상기 옵션과 유사하지만 스택 추적도 캡처합니다. Unity는 이런 예외에 대한 확인을 코드에 포함시켜서 예외를 생성하므로, 이 옵션을 선택하면 성능이 둔화되고 브라우저 메모리 사용이 증가합니다. 디버깅에만 이 옵션을 사용하고 항상 64비트 브라우저에서 테스트해야 합니다.

Publishing Settings__를 선택하여 Data Caching__에 접근합니다.

Data Caching

To access Data Caching, select Publishing Settings (File > Build Settings > Player Settings > WebGL > Publishing Settings). This enables the browser to cache the main data files into the IndexedDB database.

Using the default browser HTTP cache does not guarantee that the browser caches a particular response. This is because the browser HTTP cache has limited space, and the browser might not be able to cache files that are too large.

To improve your loading speed, IndexedDB allows you to cache files above the browser limit. When you cache more files, you increase the chance that downloaded content is available on the user’s machine during the next run of the build.

Data Caching only caches the .data files in the IndexedDB cache for HTTP responses. To cache AssetBundles, you need to enable Data Caching and override unityInstance.Module.cacheControl(). To do this, make sure Module.cacheControl(url) returns must-revalidate for the requested AssetBundle URL. For example, you can override the unityInstance.Module.cacheControl() function in the fulfillment callback of the Promise that createUnityInstance() returns. For further information on createUnityInstance() see WebGL: Compressed builds and server configuration.

WebGL용으로 퍼블리시하는 경우 콘텐츠가 시작되기 전에 사용자가 충분한 다운로드 시간을 얻을 수 있도록 빌드 크기를 작게 유지하는 것이 중요합니다. 에셋 크기를 줄일 수 있는 방법에 대한 일반적인 팁은 빌드 파일 크기 축소 문서를 참조하십시오.

배포 크기

WebGL용으로 퍼블리시하는 경우 콘텐츠가 시작되기 전에 사용자가 충분한 다운로드 시간을 얻을 수 있도록 빌드 크기를 작게 유지하는 것이 중요합니다. 에셋 크기를 줄일 수 있는 방법에 대한 일반적인 팁은 빌드 파일 크기 축소 문서를 참조하십시오.

WebGL 관련 힌트와 팁

  • 텍스처 임포터에서 모든 압축된 텍스처를 Crunch 텍스처 압축 포맷으로 지정해야 합니다.

  • 개발 빌드를 배포하지 말아야 합니다. 빌드는 압축되거나 최소화되지 않으므로 파일 크기가 훨씬 더 큽니다.

  • 빌드에 예외가 필요하지 않은 경우 Player 설정(메뉴: Edit > Project Settings 에서 Player 카테고리 선택)에서 Publishing Settings 패널을 열고 Enable ExceptionsNone 으로 설정해야 합니다.

  • Player 설정(메뉴: Edit > Project Settings 에서 Player 카테고리 선택)에서 Other Settings 패널을 열고 Strip Engine Code 를 활성화하여 빌드 효율성을 높입니다.

  • 타사 관리 dll을 사용하는 경우 많은 종속성이 포함되어 있어 생성된 코드 크기가 매우 커질 수 있으므로 주의해야 합니다.

릴리스 빌드를 만드는 경우 Unity는 WebGL Player 설정의 Publishing Settings 패널에서 선택한 Compression Format 에 따라 빌드 출력 파일을 압축합니다.

각 옵션과 옵션을 사용하여 빌드를 퍼블리시하는 방법에 대한 자세한 내용은 압축된 빌드 배포 문서를 참조하십시오.

에셋 번들

콘텐츠가 시작되기 전에 모든 에셋 데이터를 다운로드해야 하므로, 에셋을 주 데이터 파일에서 에셋 번들로 이동할지 고려해야 합니다. 이렇게 하면 빠르게 로드되는 콘텐츠를 위해 작은 로더 씬을 만들 수 있습니다. 그러면 사용자 콘텐츠를 이용하는 동안 에셋이 동적으로 로드됩니다. 또한 에셋 번들은 에셋 데이터 메모리를 관리하는 데도 도움이 됩니다. AssetBundle.Unload를 호출하여 더 이상 필요하지 않은 에셋의 에셋 데이터를 메모리에서 언로드할 수 있습니다.

WebGL 플랫폼에서 에셋 번들을 사용할 때 고려해야 할 사항이 몇 가지 있습니다.

  • 주 빌드에 사용되지 않는 에셋 번들의 클래스 타입을 사용하면 Unity가 해당 클래스에 대한 코드를 빌드에서 스트리핑할 수 있습니다. 이로 인해 에셋 번들에서 에셋을 로드하려고 할 때 실패할 수 있습니다. BuildPlayerOptions.assetBundleManifestPath를 사용하여 이 문제를 해결하거나 아래의 스트리핑에 대한 섹션에서 다른 옵션에 대해 알아보십시오.

  • WebGL은 스레딩을 지원하지 않지만 다운로드 완료 시 http 다운로드가 가능합니다. 따라서 Unity WebGL 빌드는 메인 스레드를 차단하는 다운로드가 완료되면 메인 스레드에서 에셋 번들 데이터를 압축 해제해야 합니다. 이를 피하는 방법을 선택하면 LZMA 에셋 번들 압축을 WebGL상의 에셋 번들에 사용할 수 없습니다. 대신 LZ4를 사용해 에셋 번들이 압축 해제됩니다. LZ4는 필요 시 매우 효율적으로 압축 해제할 수 있습니다. LZ4보다 더 크기가 작은 압축이 필요하다면 에셋 번들에서 (LZ4 압축 위에) gzip 또는 Brotli 압축을 사용하도록 웹 서버를 설정할 수 있습니다. 자세한 방법은 압축 빌드 배포에 대한 문서를 참고하십시오.

  • WWW.LoadFromCacheOrDownload를 사용한 에셋 번들 캐싱은 WebGL에서 브라우저의 IndexedDB API를 사용하여 지원됩니다. 캐싱은 사용자의 컴퓨터에서 구현됩니다. IndexedDB는 일부 브라우저에서 제한적으로 지원될 수 있으며, 해당 브라우저에서는 디스크에 데이터를 저장하기 위해 사용자에게 허가를 요청할 수 있습니다. 자세한 내용은 WebGL 브라우저 호환성 문서를 참조하십시오.

스트리핑

Unity는 사용되지 않은 모든 코드를 빌드에서 기본적으로 제거합니다. Player 설정(메뉴: Edit > Project Settings 에서 Player 카테고리 선택)을 통해 이 설정을 변경할 수 있습니다. Other Settings 패널을 선택하여 Strip Engine Code 옵션에 액세스해야 합니다. 스트리핑을 활성화하여 빌드하는 것이 더 좋습니다.

코드 스트리핑을 사용하면 Unity는 스크립트 코드에서 레퍼런스되어 사용되거나 씬의 직렬화된 데이터에 사용되는 UnityObject 파생 클래스를 프로젝트에서 검색합니다. 그런 다음 사용되는 클래스가 없는 Unity 서브시스템을 빌드에서 제거합니다. 그러면 빌드의 코드가 감소하여 다운로드 크기가 작아지고 파싱할 코드도 감소합니다. 따라서 코드가 더 빨리 실행되고 메모리를 덜 사용합니다.

코드 스트리핑 관련 문제

실제로 필요한 코드가 코드 스트리핑 도중 제거되는 경우 프로젝트에 문제가 발생할 수 있습니다. 예를 들어, 메인 빌드에 포함되어 있지 않아 제거된 클래스를 포함하는 에셋 번들을 런타임 시점에 로드하면 문제가 발생합니다. 이러한 문제가 발생하면 아래와 같이, 브라우저의 JavaScript 콘솔에서 오류 메시지가 표시됩니다(추가 오류 역시 발생할 수 있습니다).

Could not produce class with ID XXX

To troubleshoot these errors, look up the ID (such as XXX in the example above) in the Class ID Reference to see which class it is trying to create an instance of. In such cases, you can force Unity to include the code for that class in the build, either by adding a reference to that class to your scripts or to your Scenes, or by adding a link.xml file to your project.

Below is an example which makes sure that the Collider class (and therefore the Physics module) gets preserved in a project. Add this XML code to a file called link.xml, and put that file into your Assets folder.

<linker>
    <assembly fullname="UnityEngine">
        <type fullname="UnityEngine.Collider" preserve="all"/>
    </assembly>
</linker>

스트리핑으로 인해 빌드에 문제가 발생한다고 의심될 경우 테스트 중에 Strip Engine Code 옵션을 비활성화하는 방법도 시도해 볼 수 있습니다.

Unity does not provide a convenient way to see which modules and classes are included in a build, which would allow you to optimize your project to strip well. However, to get an overview of included classes and modules, you can look at the generated file Temp/StagingArea/Data/il2cppOutput/UnityClassRegistration.cpp after making a build.

Note that the Strip Engine Code option only affects Unity engine code. IL2CPP always strips byte code from your managed dlls and scripts. This can cause problems when you need to reference managed types dynamically through reflection rather than through static references in your code. If you need to access types through reflection, you may also need to set up a link.xml file to preserve those types. See the documentation page on iOS Build size optimization for more information on link.xml files.

빌드 출력 파일 이동

To change the location of your Build folder, change the URL of the JSON file (the second argument of the UnityLoader.instantiate) in the index.html file.

To change the location of the files inside the Build folder, change their URLs (that is, dataUrl, wasmCodeUrl, wasmMemoryUrl, and wasmFrameworkUrl) in the JSON file. All non-absolute URLs in the JSON file are treated as URLs relative to the location of the JSON file. You can specify URLs on external servers for these if you want to host your files on a content distribution network (CDN), but you need to make sure that the hosting server has enabled Cross Origin Resource Sharing (CORS) for this to work. See the manual page on WebGL networking for more information about CORS.

인크리먼트 빌드

The C++ code generated for your project by IL2CPP is compiled incrementally; that is, only generated C++ code that has changed since the last build is compiled again. Unchanged source code re-uses the same object files generated for the previous build. The object files used for incremental C++ builds are stored in the Library/il2cpp_cache directory in your Unity project.

To perform a clean, from-scratch build of the generated C++ code which doesn’t use incremental compiling, delete the Library/il2cpp_cache directory in your Unity project. Note that if the Unity Editor version differs from the one used for the previous WebGL build, Unity does a clean, from-scratch build automatically.


  • Unity 2017.3에 Full Without Stacktrace 추가됨
  • Unity 2019.1에서 asm.js 링커 타겟 삭제됨
  • Build file updates and Data Caching added in Unity 2020.1
WebGL 플레이어 설정
WebGL: Compressed builds and server configuration