JS代码
// generate-ue-plugin-doc.js
/*** npm install iconv-lite jschardet* 如果需要处理非 UTF-8 编码的文件，可以在 safeReadFile 中使用 iconv-lite 和 jschardet 来检测和转换编码。* node generate-ue-plugin-doc.js <插件根目录>*/
const fs = require('fs');
const path = require('path');
const iconv = require('iconv-lite');
const jschardet = require('jschardet');// ========== 工具函数 ==========// 判断是否为文本文件（可安全读取）
function isTextFile(filePath) {const textExts = ['.ini', '.json', '.xml', '.txt', '.csv', '.md', '.cs', '.h', '.cpp', '.uplugin'];const ext = path.extname(filePath).toLowerCase();return textExts.includes(ext);
}// 判断是否为二进制资源（如 uasset）
function isBinaryAsset(filePath) {const binaryExts = ['.uasset', '.umap', '.uexp', '.ubulk'];const ext = path.extname(filePath).toLowerCase();return binaryExts.includes(ext);
}function generateTree(dir) {const rootName = path.basename(dir);const lines = [`${rootName}/`];function walk(currentPath, prefix = '') {let items;try {items = fs.readdirSync(currentPath);} catch {return; // 跳过无法读取的目录}// 排序：目录在前，文件在后，同类型按名称排序items.sort((a, b) => {const aPath = path.join(currentPath, a);const bPath = path.join(currentPath, b);const aStat = fs.statSync(aPath);const bStat = fs.statSync(bPath);if (aStat.isDirectory() && !bStat.isDirectory()) return -1;if (!aStat.isDirectory() && bStat.isDirectory()) return 1;return a.localeCompare(b);});for (let i = 0; i < items.length; i++) {const item = items[i];const itemPath = path.join(currentPath, item);const isLast = i === items.length - 1;// 直接显示所有项（无过滤）lines.push(prefix + (isLast ? '└── ' : '├── ') + item);// 如果是目录，递归进入if (fs.statSync(itemPath).isDirectory()) {const nextPrefix = prefix + (isLast ? ' ' : '│ ');walk(itemPath, nextPrefix);}}}walk(dir);return lines.join('\n');
}// 递归收集文件（按扩展名过滤或全收）
function collectFilesRecursively(dir, filterExt = null) {if (!fs.existsSync(dir)) return [];const results = [];const items = fs.readdirSync(dir).sort();for (const item of items) {const fullPath = path.join(dir, item);const stat = fs.statSync(fullPath);const relPath = path.relative(dir, fullPath).replace(/\\/g, '/');if (stat.isDirectory()) {results.push(...collectFilesRecursively(fullPath, filterExt));} else {if (!filterExt || item.toLowerCase().endsWith(filterExt.toLowerCase())) {results.push({label: relPath,path: fullPath});}}}return results;
}// 安全读取文本内容（二进制文件返回特殊标记）
async function safeReadFile(filePath) {if (isBinaryAsset(filePath)) {return '[Binary file - content not displayed]';}if (!isTextFile(filePath)) {return '[Unsupported file type - skipped content]';}try {await fs.promises.access(filePath);const buffer = await fs.promises.readFile(filePath); // 读为 Buffer// 如果文件为空if (buffer.length === 0) return '';// 尝试检测编码（fallback 到 utf8）const detected = jschardet.detect(buffer);let encoding = detected.encoding;// 限制只处理常见编码，避免误判if (!['UTF-8', 'GB2312', 'GBK', 'GB18030'].includes(encoding)) {encoding = 'UTF-8';}// 特别处理：Windows 记事本保存的 ANSI 文件通常被识别为 'windows-1252'，但中文环境下其实是 GBKif (encoding === 'windows-1252' && buffer.some(b => b > 127)) {encoding = 'GBK'; // 中文系统下更可能是 GBK}// 解码let content;try {content = iconv.decode(buffer, encoding);} catch (e) {// 如果解码失败，回退到 UTF-8（容忍部分错误）content = iconv.decode(buffer, 'UTF-8', { stripBOM: true });}return content.trim() === '' ? '' : content;} catch (err) {console.warn(`Failed to read file ${filePath}:`, err.message);return null;}
}// 获取代码块语言标识
function getLangByExt(ext) {const map = {'.h': 'cpp','.cpp': 'cpp','.cs': 'csharp','.uplugin': 'json','.ini': 'ini','.json': 'json','.xml': 'xml','.txt': 'plaintext','.md': 'markdown'};return map[ext.toLowerCase()] || 'plaintext';
}// ========== 主逻辑 ==========async function main(pluginDir) {const pluginName = path.basename(pluginDir);// ====== 1. 插件结构 ======let markdown = `# UE5.7插件：${pluginName}\n\n`;markdown += `## 插件结构\n\n`;markdown += '```txt\n';markdown += generateTree(pluginDir);markdown += '\n```\n\n';// ====== 2. 插件代码 ======markdown += `## 插件代码\n\n`;const allFiles = [];// --- 基础文件 ---allFiles.push({ label: `${pluginName}.uplugin`, path: path.join(pluginDir, `${pluginName}.uplugin`) },{ label: `${pluginName}.Build.cs`, path: path.join(pluginDir, 'Source', pluginName, `${pluginName}.Build.cs`) });// --- Public/*.h ---const publicDir = path.join(pluginDir, 'Source', pluginName, 'Public');allFiles.push(...collectFilesRecursively(publicDir).filter(f => f.path.endsWith('.h')));// --- Private/*.cpp ---const privateDir = path.join(pluginDir, 'Source', pluginName, 'Private');allFiles.push(...collectFilesRecursively(privateDir).filter(f => f.path.endsWith('.cpp')));// --- Config/*.ini ---const configDir = path.join(pluginDir, 'Config');if (fs.existsSync(configDir)) {const configFiles = collectFilesRecursively(configDir);allFiles.push(...configFiles.map(f => ({label: `Config/${f.label}`,path: f.path})));}// --- Content/* (all files) ---const contentDir = path.join(pluginDir, 'Content');if (fs.existsSync(contentDir)) {const contentFiles = collectFilesRecursively(contentDir);allFiles.push(...contentFiles.map(f => ({label: `Content/${f.label}`,path: f.path})));}// 排序：按 label 字母序allFiles.sort((a, b) => a.label.localeCompare(b.label));// 生成 Markdownfor (const file of allFiles) {const ext = path.extname(file.path);const lang = getLangByExt(ext);markdown += `### ${file.label}\n\n`;markdown += `\`\`\`${lang}\n`;const content = await safeReadFile(file.path);if (content !== null) {markdown += content;} else {markdown += '// 文件不存在';}markdown += '\n```\n\n';}// 输出const outputPath = path.join(pluginDir, `${pluginName}_DOC.md`);await fs.promises.writeFile(outputPath, markdown, 'utf8');console.log(`✅ 文档已生成: ${outputPath}`);
}// ========== 启动 ==========
const pluginPath = process.argv[2];
if (!pluginPath) {console.error('用法: node generate-ue-plugin-doc.js <插件根目录>');process.exit(1);
}main(path.resolve(pluginPath)).catch(console.error);
效果图
![屏幕截图 2026-03-04 173042]()
