# 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.