File System

The file system consists of a set of storage areas isolated based on Mini Programs and users and a set of appropriate management APIs. A globally unique file system manager is obtained via wx.getFileSystemManager(). The management operations for all file systems are called via FileSystemManager.

var fs = wx.getFileSystemManager()

Files are divided into two categories:

  • Code package file: A file added in the project directory.
  • Local file: A file generated locally by calling an API, or downloaded over the network and stored locally.

Local files are divided into three types:

  1. Local temporary file: A file that is temporarily generated and will be recycled at any time. The storage space of local temporary files is unlimited.
  2. Local cache file: A file generated by a Mini Program after caching a local temporary file via an API. The directory and file name cannot be customized. Normal Mini Programs can store up to 10 MB of local cache and local user files, while game-type Mini Programs can store up to 50 MB.
  3. Local user file: A file generated by a Mini Program after caching a local temporary file via an API. The directory and file name can be customized. Normal Mini Programs can store up to 10 MB of local user and local cache files, while game-type Mini Programs can store up to 50 MB.

Code Package File

Due to limited size, code package files are those needed for the first load. Large files and those that require dynamic replacement should not be added to the code package, but should be downloaded to the local device via the download API after the Mini Game is launched.

Access code package files

To access code package files, write the file path from the project root directory. Relative paths are not supported. image.png

Modify code package files

Files in the code package cannot be dynamically modified or deleted after running. Modifying the code package files requires a version re-release.

Local File

Local file refers to an individual file storage isolated based on users after the Mini Program is added to the mobile device by the user. A Weixin user cannot access the files of other users who have logged in on the same phone, and a user who have multiple appIds cannot access files under one appId using another appId. Local file sandbox.png

The file path of a local file follows this format:

{{Protocol Name}}://File Path

The protocol name is "wxfile" in the Weixin app for iOS/Android and "http" in the Weixin DevTools. Developers can ignore this difference, and should not hard code a complete file path in the code.

Local temporary file

Local temporary file can only be generated by calling a specific API. However, you do not have the permission to write to the file directly. After a local temporary file is generated, it is valid only during the Mini Program's current lifecycle and is not available after the Mini Program restarts. Therefore, you cannot save the local temporary file path for later use. To use a local temporary file later, you can convert it to a local cache file or a local user file via the FileSystemManager.saveFile() or FileSystemManager.copyFile() API.

Example
wx.chooseImage({
  success: function (res) {
    var tempFilePaths = res.tempFilePaths // Each entry of tempFilePaths is a local temporary file path
  }
})

Local cache file

Local cache file can only be generated by calling a specific API and cannot be written directly. After a local cache file is generated, it is still available after the Mini Program restarts. Local cache files can only be obtained by saving the local temporary files via the FileSystemManager.saveFile() API.

Example
fs.saveFile({
  tempFilePath: '', // Pass a local temporary file path
  success(res) {
    console.log(res.savedFilePath) // res.savedFilePath is a local cache file path
  }
})

Note: The local cache file was an initial design idea. From version 1.7.0, we provide a more complete local user file, which can completely cover the features of local cache file. If compatibility is not required for versions lower than 1.7.0, you can choose not to use local cache file.

Local user file

Local user file is a new concept that has been added since version 1.7.0. We provide a user file directory for developers, who have completely free read/write access to this directory. The path to this directory is available via wx.env.USER_DATA_PATH.

Example
// Create a hello.txt file in the local user file directory and write "hello, world" to it
const fs = wx.getFileSystemManager()
fs.writeFileSync(`${wx.env.USER_DATA_PATH}/hello.txt`, 'hello, world', 'utf8')

Read/Write Permission

API/Component Read Write
Code package file Yes No
Local temporary file Yes No
Local cache file Yes No
Local user file Yes Yes

Erasion Rules

  • Local temporary files are only guaranteed to persist during the Mini Program's current lifecycle. Once the Mini Program is closed, these files can be erased and may not be available at the next cold start.
  • Local cache files and local user files are erased only when the code package is erased.