# File System

The file system is a set of storage mechanisms provided by the Mini-Program, isolated by Mini-Program and user dimensions, along with a corresponding set of management interfaces.

You can obtain the globally unique file system manager by calling ft.getFileSystemManager(). All file system management operations are invoked through FileSystemManager.

var fs = ft.getFileSystemManager()

Files are mainly divided into two categories:

  • Code Package Files: Code package files refer to files added within the project directory.
  • Local Files: Files generated locally by calling interfaces or downloaded from the network and stored locally.

Local files are further divided into three types:

# 1. Code Package Files

Due to the size limitation of code package files, they are suitable for placing files required during the initial load. For files with large content or those that need dynamic replacement, it is not recommended to add them to the code package. It is recommended to download them locally using download interfaces after the Mini-Program starts.

# 1.1 Accessing Code Package Files

Code package files are accessed by writing the file path starting from the project root directory. Relative path syntax is not supported. For example: /a/b/c and a/b/c are valid, while ./a/b/c and ../a/b/c are invalid.

# 1.2 Modifying Code Package Files

Files within the code package cannot be dynamically modified or deleted after runtime. Modifying code package files requires republishing a new version.

# 2. Local Files

Local files refer to an independent file storage area allocated after the Mini-Program is added to the user's device.

The file paths for local files all follow this format:

{{Protocol Name}}://File Path

# 2.1 Local Temporary Files

Local temporary files can only be generated by calling specific interfaces and cannot have content written directly to them. Once generated, local temporary files are only guaranteed to be valid during the current lifecycle; they may not be available after a restart. If you need to ensure the file is available without re-downloading upon the next startup, you can convert the local temporary file into a local cached file or a local user file using the FileSystemManager.saveFile() or FileSystemManager.copyFile() interface.

The cleanup policy for temporary files is as follows: After the Mini-Program exits, the system checks the temporary file usage of that Mini-Program. If it does not exceed 2GB, no cleanup is performed. If it exceeds the limit, files are cleaned up based on their last used time, starting from the least recently used. The system also checks the temporary file usage of all Mini-Programs. If the total exceeds 6GB, cleanup is performed on a per-Mini-Program basis.

Therefore, when downloading temporary files, developers can first check if the file exists using FileSystemManager.access() to reduce redundant downloads and improve the user experience.

# Example

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

# 2.2 Local Cached Files

Local cached files can only be generated by calling specific interfaces and cannot have content written directly to them. Once generated, local cached files remain available after a restart. Local cached files can only be obtained by saving a local temporary file using the FileSystemManager.saveFile() interface.

# Example

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

Note

Local cached files were part of the initial design. Starting from version 1.7.0, a more fully-featured local user file system was provided, which can completely cover the functionality of local cached files. If compatibility with versions below 1.7.0 is not required, you may choose not to use local cached files.

# 2.3 Local User Files

The Mini-Program provides a user file directory for developers, who have complete read and write permissions for this directory. The path to this directory can be obtained via ft.env.USER_DATA_PATH.

# Example

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

# 2.4 Read/Write Permissions

Interface / Component Read Write
Code Package Files Yes No
Local Temporary Files Yes No
Local Cached Files Yes No
Local User Files Yes Yes

# 2.5 Cleanup Policy

  • Local temporary files are only guaranteed to exist during the current lifecycle of the Mini-Program. Once the Mini-Program is closed, they may be cleaned up, meaning availability is not guaranteed upon the next cold start.
  • The cleanup timing for local cached files and local user files is the same as for the code package; they are only cleaned up when the code package itself is cleaned.
© FinClip with ❤ , Since 2017