为缓解 Windows 下路径名过长的 问题， 略微加快一下 require的速度以及隐藏你的源代码，你可以选择把你的应用打包成 asar档案文件，这只需要对你的源代码做一些很小的改动。

大部分用户可以毫不费力地使用这个功能，因为它electron-packager,、electron-forge和electron-builder中都得到了支持，开箱即用。 如果你没有使用这些工具中的任何一个，那么请继续阅读。

Application Packaging

To mitigate issues around long path names on Windows, slightly speed up require and conceal your source code from cursory inspection, you can choose to package your app into an asar archive with little changes to your source code.

Most users will get this feature for free, since it's supported out of the box by electron-packager, electron-forge, and electron-builder. If you are not using any of these tools, read on.

生成 asar 档案文件

asar 是一种将多个文件合并成一个文件的类 tar 风格的归档格式。 Electron 可以无需解压整个文件，即可从其中读取任意文件内容。

参照如下步骤将你的应用打包成 asar归档文件。

Generating asar Archives

An asar archive is a simple tar-like format that concatenates files into a single file. Electron can read arbitrary files from it without unpacking the whole file.

Steps to package your app into an asar archive:

1. 安装 asar 实用程序

$ npm install -g asar

1. Install the asar Utility

$ npm install -g asar

2. 使用 asar pack 打包

$ asar pack your-app app.asar

2. Package with asar pack

$ asar pack your-app app.asar

使用 asar 档案文件

在 Electron 中有两类 APIs：Node.js 提供的 Node API 和 Chromium 提供的 Web API。 这两种 API 都支持从 asar 档案中读取文件。

Using asar Archives

In Electron there are two sets of APIs: Node APIs provided by Node.js and Web APIs provided by Chromium. Both APIs support reading files from asar archives.

Node API

由于 Electron 中打了特别补丁， Node API 中如 fs.readFile 或者 require 之类 的方法可以将 asar 视之为虚拟文件夹，读取 asar 里面的文件就和从真实的文件系统中读取一样。

例如，假设我们在 /path/to 文件夹下有个 example.asar 包：

$ asar list /path/to/example.asar
/app.js
/file.txt
/dir/module.js
/static/index.html
/static/main.css
/static/jquery.min.js

从 asar 档案读取一个文件：

const fs = require('fs')
fs.readFileSync('/path/to/example.asar/file.txt')

列出档案根目录下的所有文件：

const fs = require('fs')
fs.readdirSync('/path/to/example.asar')

使用档案中的模块：

require('/path/to/example.asar/dir/module.js')

你也可以使用 BrowserWindow 来显示一个 asar 档案里的 web 页面：

const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
win.loadURL('file:///path/to/example.asar/static/index.html')

Node API

With special patches in Electron, Node APIs like fs.readFile and require treat asar archives as virtual directories, and the files in it as normal files in the filesystem.

For example, suppose we have an example.asar archive under /path/to:

$ asar list /path/to/example.asar
/app.js
/file.txt
/dir/module.js
/static/index.html
/static/main.css
/static/jquery.min.js

Read a file in the asar archive:

const fs = require('fs')
fs.readFileSync('/path/to/example.asar/file.txt')

List all files under the root of the archive:

const fs = require('fs')
fs.readdirSync('/path/to/example.asar')

Use a module from the archive:

require('/path/to/example.asar/dir/module.js')

You can also display a web page in an asar archive with BrowserWindow:

const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
win.loadURL('file:///path/to/example.asar/static/index.html')

Web API

在 Web 页面里，用 file: 协议可以获取 asar 包中文件。和 Node API 一样，视 asar 包如虚拟文件夹。

例如，用 $.get 获取文件:

<script>
let $ = require('./jquery.min.js')
$.get('file:///path/to/example.asar/file.txt', (data) => {
  console.log(data)
})
</script>

Web API

In a web page, files in an archive can be requested with the file: protocol. Like the Node API, asar archives are treated as directories.

For example, to get a file with $.get:

<script>
let $ = require('./jquery.min.js')
$.get('file:///path/to/example.asar/file.txt', (data) => {
  console.log(data)
})
</script>

把 asar 档案当作一个普通的文件

某些情况下，如：对 asar 档案文件进行校验，我们需要像读取 “文件” 那样读取 asar 档案文件。 为此你可以使用内置的没有asar功能的和原始fs模块一模一样的original-fs模块。

const originalFs = require('original-fs')
originalFs.readFileSync('/path/to/example.asar')

您也可以将 process.noAsar 设置为 true 以禁用 fs 模块中对 asar 的支持：

const fs = require('fs')
process.noAsar = true
fs.readFileSync('/path/to/example.asar')

Treating an asar Archive as a Normal File

For some cases like verifying the asar archive's checksum, we need to read the content of an asar archive as a file. For this purpose you can use the built-in original-fs module which provides original fs APIs without asar support:

const originalFs = require('original-fs')
originalFs.readFileSync('/path/to/example.asar')

You can also set process.noAsar to true to disable the support for asar in the fs module:

const fs = require('fs')
process.noAsar = true
fs.readFileSync('/path/to/example.asar')

Node API 的局限性

尽管我们已经尽了最大努力使得 asar 包在 Node API 下的应用尽可能的趋向于真实的目录结构，但仍有一些底层 Node API 我们无法保证其正常工作。

Limitations of the Node API

Even though we tried hard to make asar archives in the Node API work like directories as much as possible, there are still limitations due to the low-level nature of the Node API.

档案文件是只读的

档案文件中的内容不可更改，所以 Node APIs 里那些会修改文件的方法在使用asar 归档文件时都无法正常工作.

Archives Are Read-only

The archives can not be modified so all Node APIs that can modify files will not work with asar archives.

工作目录不能设置为档案文件里的目录

尽管 asar 档案是虚拟文件夹，但其实并没有真实的目录架构对应在文件系统里，所以你不可能将 working Directory 设置成 asar 包里的一个文件夹。 将 asar 中的文件夹以 cwd 形式作为参数传入一些 API 中也会报错。

Working Directory Can Not Be Set to Directories in Archive

Though asar archives are treated as directories, there are no actual directories in the filesystem, so you can never set the working directory to directories in asar archives. Passing them as the cwd option of some APIs will also cause errors.

某些 API 需要额外解压档案包

大部分 fs API 可以无需解压即从 asar 档案中读取文件或者文件的信息，但是在处理一些依赖真实文件路径的底层系统方法时，Electron 会将所需文件解压到临时目录下，然后将临时目录下的真实文件路径传给底层系统方法使其正常工作。 对于这类API，会增加一些开销。

以下是一些需要额外解压的 API：

• child_process.execFile
• child_process.execFileSync
• fs.open
• fs.openSync
• process.dlopen - 用在 require 原生模块时

Extra Unpacking on Some APIs

Most fs APIs can read a file or get a file's information from asar archives without unpacking, but for some APIs that rely on passing the real file path to underlying system calls, Electron will extract the needed file into a temporary file and pass the path of the temporary file to the APIs to make them work. This adds a little overhead for those APIs.

APIs that requires extra unpacking are:

• child_process.execFile
• child_process.execFileSync
• fs.open
• fs.openSync
• process.dlopen - Used by require on native modules

fs.stat 的不真实统计信息

对 asar 档案中的文件取 fs.stat，返回的 Stats 对象不是精确值，因为这些文件不是真实存在于文件系统里。 所以除了文件大小和文件类型以外，你不应该依赖 Stats 对象的值。

Fake Stat Information of fs.stat

The Stats object returned by fs.stat and its friends on files in asar archives is generated by guessing, because those files do not exist on the filesystem. So you should not trust the Stats object except for getting file size and checking file type.

执行asar档案内的二进制文件

Node 中有一些可以执行程序的 API，如 child_process.exec，child_process.spawn 和 child_process.execFile 等， 但只有 execFile 可以执行 asar 包中的程序。

因为 exec 和 spawn 允许 command 替代 file 作为输入，而 command 是需要在 shell 下执行的. 目前没有 可靠的方法来判断 command 中是否在操作一个 asar 包中的文件，而且即便可以判断，我们依旧无法保证可以在无任何 副作用的情况下替换 command 中的文件路径。

Executing Binaries Inside asar Archive

There are Node APIs that can execute binaries like child_process.exec, child_process.spawn and child_process.execFile, but only execFile is supported to execute binaries inside asar archive.

This is because exec and spawn accept command instead of file as input, and commands are executed under shell. There is no reliable way to determine whether a command uses a file in asar archive, and even if we do, we can not be sure whether we can replace the path in command without side effects.

添加未打包的文件到 asar 档案

如上所述，一些节点APIs将在 调用时解压文件。除了性能问题之外，各种抗病毒扫描器可能会因此行为触发 。

有一个解决方法，您可以使用 --unpack 选项保持各种文件不被压缩。 在下面这个例子中，原生 Node.js 模块的共享库将不会被打包：

$ asar pack app app.asar --unpack *.node

运行命令后，您将会看到 app.asar.unpacked 文件夹与 app.asar 文件一起被创建了。 没有被打包的文件和 app.asar 会一起存档发布。

Adding Unpacked Files to asar Archives

As stated above, some Node APIs will unpack the file to the filesystem when called. Apart from the performance issues, various anti-virus scanners might be triggered by this behavior.

As a workaround, you can leave various files unpacked using the --unpack option. In the following example, shared libraries of native Node.js modules will not be packed:

$ asar pack app app.asar --unpack *.node

After running the command, you will notice that a folder named app.asar.unpacked was created together with the app.asar file. It contains the unpacked files and should be shipped together with the app.asar archive.