Files NJS

Files NJS 是一個功能強大的 NekoJS 附屬模組。

功能

• 檔案操作：讀取、寫入、追加、複製、移動和刪除檔案
• 目錄管理：列出、建立和監視目錄
• 檔案監控：監視檔案變更和內容修改
• 檔案分析：比較檔案、計算MD5雜湊值、搜尋檔案內容
• 備份管理：建立和管理檔案備份
• 歸檔操作：建立ZIP壓縮包

API 部分參考（不完整）

檔案讀寫操作

// 讀取檔案內容
let content = FilesJS.readFile('kubejs/config/my_config.txt');

// 寫入檔案
FilesJS.writeFile('kubejs/data/output.txt', '你好，世界！');

// 追加到檔案
FilesJS.appendFile('kubejs/logs/my_log.txt', '新的日誌條目');

// 追加單行
FilesJS.appendLine('kubejs/logs/my_log.txt', '新的一行');

// 寫入多行
FilesJS.writeLines('kubejs/data/lines.txt', ['第一行', '第二行', '第三行']);

// 讀取所有行
let lines = FilesJS.readLines('kubejs/data/lines.txt');

// 讀取最後N行
let lastLines = FilesJS.readLastLines('kubejs/logs/latest.log', 10);

// 儲存指令碼檔案（自動新增.js副檔名和時間戳記註解）
FilesJS.saveScript('kubejs/scripts/new_script', 'console.log("Hello");');

檔案管理操作

// 檢查檔案是否存在
if (FilesJS.exists('kubejs/scripts/my_script.js')) {
    // 執行操作
}

// 刪除檔案
FilesJS.delete('kubejs/temp/oldfile.txt');

// 複製檔案
FilesJS.copy('source.txt', 'target.txt');

// 移動檔案
FilesJS.move('old/path.txt', 'new/path.txt');

// 重新命名檔案
FilesJS.renameFile('old_name.txt', 'new_name.txt');

// 建立目錄
FilesJS.createDirectory('kubejs/newdir');

// 檢查檔案是否為空
let isEmpty = FilesJS.isFileEmpty('kubejs/data/file.txt');

// 取得檔案MD5雜湊值
let hash = FilesJS.getFileMD5('kubejs/data/important.dat');

// 比較兩個檔案
let areEqual = FilesJS.compareFiles('file1.txt', 'file2.txt');

批量檔案操作

// 合併多個檔案
FilesJS.mergeFiles(['file1.txt', 'file2.txt'], 'merged.txt');

// 批量複製檔案（使用萬用字元）
FilesJS.copyFiles('source/dir', 'target/dir', '*.json');

// 建立ZIP壓縮包
FilesJS.createZip('kubejs/data', 'kubejs/backups/data.zip');

// 取代檔案中的內容
FilesJS.replaceInFile('config.txt', '舊值', '新值');

目錄操作

// 列出目錄中的檔案
let files = FilesJS.listFiles('kubejs/data');

// 遞迴列出所有檔案
let allFiles = FilesJS.listFilesRecursively('kubejs/scripts');

// 取得檔案資訊
let fileInfo = FilesJS.getFileInfo('kubejs/config/settings.json');
// fileInfo包含：exists, size, lastModified, isDirectory, isFile, isReadable, isWritable

檔案監控

// 監視目錄變更
FilesJS.watchDirectory('kubejs/data', (changedPath) => {
    console.log('檔案已更改:', changedPath);
});

// 監視檔案內容變更（帶相似度閾值）
FilesJS.watchContentChanges('kubejs/config/dynamic.json', 0.1);

// 監視符合特定模式的檔案
FilesJS.watchFilePattern('kubejs/scripts', '*.js');

// 監視檔案大小
FilesJS.watchFileSize('kubejs/data/growing.log', 1024 * 1024); // 1MB閾值

備份系統

// 立即建立備份
FilesJS.backupFile('kubejs/important/data.json');

// 排程備份（延遲執行tick）
FilesJS.scheduleBackup('kubejs/config/settings.json', 100); // 100 tick後開始備份這個檔案

// 搜尋檔案內容
let matches = FilesJS.searchInFile('kubejs/logs/latest.log', 'ERROR');

安全性和限制

允許存取的目錄

只能存取以下目錄中的檔案：

• kubejs/
• config/
• logs/
• backups/
• scripts/

檔案大小限制

• 最大檔案大小：5MB
• 寫入操作的內容大小限制：5MB

檔案類型限制

允許的檔案副檔名：

• .txt
• .json
• .js
• .log
• .cfg
• .toml
• .properties
• .backup
• 還有很多

安全措施

• 禁止存取Minecraft執行個體目錄之外的檔案
• 禁止父目錄遍歷 (..)
• 關鍵操作自動建立備份
• 所有操作都進行檔案存取驗證
• 檔案大小限制檢查
• 檔案類型驗證
• 路徑安全性檢查
• 檔案副檔名驗證

錯誤處理

使用 try catch 進行例外處理

try {
    Files.writeFile('kubejs/data/test.txt', '內容');
} catch (e) {
    console.error('寫入檔案失敗:', e.message);
}

最佳實務

1. 始終在指令碼中處理例外
2. 使用適當的檔案副檔名
3. 在操作前檢查檔案大小
4. 及時清理暫存檔案
5. 對重要檔案使用備份功能
6. 謹慎監控檔案變更
7. 寫入前驗證檔案內容
8. 使用事件系統進行記錄
9. 實現適當的錯誤復原機制
10. 定期清理舊的備份檔案

效能考量

1. 大檔案操作時注意記憶體使用
2. 避免頻繁的檔案監控
3. 合理使用遞迴檔案操作
4. 適當設定監控閾值
5. 使用批量操作代替單個操作

支援

如果遇到問題或有疑問：

1. 檢查日誌中的詳細錯誤資訊
2. 驗證檔案權限和路徑
3. 確保在允許的目錄中操作
4. 檢查檔案大小限制
5. 查看事件接聽程式的日誌輸出