@flun/html-template 4.0.10

package/customize/users.json

@@ -0,0 +1,44 @@
+[
+  {
+    "id": 1775222838614,
+    "username": "admin",
+    "email": null,
+    "password": "$2b$10$u8LlXx6cbBkYYh1pnnjf3uTVVn2saj0daUb0b4QUDU9TOL1dmhg0G",
+    "emailVerified": false,
+    "emailVerificationToken": null,
+    "passwordResetToken": null,
+    "passwordResetExpires": null,
+    "twoFactorSecret": null,
+    "twoFactorEnabled": false,
+    "backupCodes": [],
+    "webauthnCredentials": [],
+    "webauthnEnabled": false,
+    "createdAt": 1775222838614,
+    "updatedAt": 1775222838614,
+    "passwordChangedAt": 1775222838614,
+    "pendingEmail": null,
+    "pendingEmailToken": null,
+    "pendingEmailExpires": null
+  },
+  {
+    "id": 1777035892336,
+    "username": "lunjack123",
+    "email": "china@lunjack.com",
+    "password": "$2b$10$r4tmKt/j0blecpxy3QNL/u2Ht5y6RcHgSwtJ87CB.vYInwPWP5As2",
+    "emailVerified": true,
+    "emailVerificationToken": null,
+    "passwordResetToken": null,
+    "passwordResetExpires": null,
+    "twoFactorSecret": null,
+    "twoFactorEnabled": false,
+    "backupCodes": [],
+    "webauthnCredentials": [],
+    "webauthnEnabled": false,
+    "createdAt": 1777035892336,
+    "updatedAt": 1777035892336,
+    "passwordChangedAt": 1777035892336,
+    "pendingEmail": null,
+    "pendingEmailToken": null,
+    "pendingEmailExpires": null
+  }
+]

package/customize/variables.js

@@ -0,0 +1,70 @@
+// customize/variables.js
+export default {
+    variables: {
+        // ============= 基础信息变量 ============
+        year: new Date().getFullYear(),
+        timestamp: Date.now(),                          // 当前时间戳
+        baseUrl: '/',
+        nodeEnv: process.env.NODE_ENV || 'development', // 当前环境
+        serverTime: new Date().toLocaleString(),        // 服务器当前时间
+        // ============ 自定义数据变量 ============
+        // 用户信息
+        user: {
+            isLoggedIn: true,
+            name: "张三",
+            membershipLevel: "VIP",
+            isGuest: false
+        },
+
+        // 产品信息
+        product: {
+            stock: 5,
+            price: 99.99
+        },
+
+        // 产品列表
+        products: [
+            { name: "产品A", price: 100, stock: 10, isNew: true },
+            { name: "产品B", price: 200, stock: 5, isNew: false },
+            { name: "产品C", price: 300, stock: 0, isNew: true },
+            { name: "产品D", price: 150, stock: 8, isNew: false },
+            { name: "产品E", price: 250, stock: 3, isNew: true },
+            { name: "产品F", price: 350, stock: 7, isNew: false }
+        ],
+
+        // 团队成员信息
+        teamMembers: [
+            {
+                name: "李四",
+                position: "技术总监",
+                department: "技术部",
+                skills: ["JavaScript", "Node.js", "Vue"]
+            },
+            {
+                name: "王五",
+                position: "设计师",
+                department: "设计部",
+                skills: ["UI设计", "UX设计", "原型设计"]
+            },
+            {
+                name: "赵六",
+                position: "产品经理",
+                department: "产品部",
+                skills: ["产品规划", "需求分析", "项目管理"]
+            }
+        ],
+
+        // 公司信息
+        companyInfo: {
+            "成立年份": "2015年",
+            "员工人数": "50+",
+            "总部地点": "北京",
+            "业务范围": "软件开发、技术咨询、产品设计",
+            "服务客户": "1000+"
+        },
+
+        // 测试空数据
+        emptyArray: [], // 空数组
+        emptyObject: {} // 空对象
+    }
+};

package/dev-server.js

@@ -0,0 +1,344 @@
+/**
+ * 开发服务器模块 - 动态模板渲染服务器
+ *
+ * 模块结构：
+ * 1. 依赖导入与服务器初始化
+ * 2. 服务器配置与端口管理(parseAndValidatePort,parseServerConfig)
+ * 3. 全局CORS中间件和静态资源配置(/static路径)
+ * 4. 服务器生命周期管理(printAvailablePages, startServer)
+ * 5. 请求页面路由处理(自动路由与模板渲染) —— 已在 startServer 内部动态添加
+ * 6. 热重载功能实现(文件监听、事件处理、服务器重启) —— setupHotReload, restartServer
+ * 7. 导出接口与启动执行(module.exports , startServer)
+ */
+
+// ==================== 1.依赖导入与服务器初始化 ====================
+import express from 'express';
+import { constants, existsSync } from 'fs';
+import http from 'http';
+import { Server as socketIo } from 'socket.io';
+import chokidar from 'chokidar';
+import { fileURLToPath, pathToFileURL } from 'url';
+import {
+	path, fsPromises, CWD, getAvailableTemplates, findEntryFile, validateTemplateFile, renderTemplate, processIncludes,
+	processVariables, loadUserFeatures, writtenFilesToIgnore, templatesAbsDir, templatesDir, staticDir, customizeDir,
+	accountDir, defaultPort, monitorFileWrites
+} from './services/templateService.js';
+import { injectScript } from './customize/hotReloadInjector.js';
+
+let server, io, watcher, cachedPages = [], unmountMonitor = null;
+const __filename = fileURLToPath(import.meta.url), __dirname = path.dirname(__filename),
+	app = express(), staticAbsDir = path.join(CWD, staticDir), customizeAbsDir = path.join(CWD, customizeDir),
+
+	// ==================== 工具函数 ====================
+	/**
+	 * 创建带WebSocket的服务器
+	 */
+	createServerWithSocket = (app, hotReload) => {
+		server = http.createServer(app);
+		if (hotReload) {
+			io = new socketIo(server);
+			io.engine.on("headers", headers => headers["Content-Type"] = "text/html; charset=utf-8");
+		}
+	},
+
+	/**
+	 * 清理资源
+	 */
+	cleanupResources = () => {
+		if (watcher) watcher.close(), watcher = null;
+		if (io) io.close(), io = null;
+		if (unmountMonitor) unmountMonitor(); unmountMonitor = null;
+	},
+
+	/**
+	 * 生成页面URL
+	 */
+	generateUrls = (page, port) => {
+		const baseUrl = `http://localhost:${port}`, url = `${baseUrl}/${page}`, needsEncoding = !/^[a-zA-Z0-9\-_.~/]+$/.test(page);
+
+		return { url, encodedUrl: `${baseUrl}/${encodeURI(page)}`, needsEncoding };
+	},
+
+	/**
+	 * 递归复制目录
+	 */
+	copyDir = async (src, dest) => {
+		await fsPromises.mkdir(dest, { recursive: true });
+		const entries = await fsPromises.readdir(src, { withFileTypes: true });
+		for (let entry of entries) {
+			const srcPath = path.join(src, entry.name), destPath = path.join(dest, entry.name);
+			if (entry.isDirectory()) await copyDir(srcPath, destPath);
+			else await fsPromises.copyFile(srcPath, destPath);
+		}
+	},
+
+	/**
+	 * 确保登录模式所需文件存在(从包内复制缺失文件)
+	 */
+	ensureAccountFiles = async () => {
+		const userAccountJs = path.join(customizeAbsDir, 'account.js'),
+			userTemplatesAccount = path.join(CWD, templatesDir, accountDir);
+		// 检查并拷贝 customize/account.js
+		try {
+			await fsPromises.access(userAccountJs, constants.F_OK);
+		} catch {
+			console.log('检测到 account=true 但缺少 customize/account.js,正在从包内复制...');
+			const pkgCustomizeDir = path.join(__dirname, customizeDir),
+				defaultAccountJs = path.join(pkgCustomizeDir, 'account.js');
+			try {
+				await fsPromises.access(defaultAccountJs, constants.F_OK);
+				await fsPromises.mkdir(customizeAbsDir, { recursive: true });
+				await fsPromises.copyFile(defaultAccountJs, userAccountJs);
+				console.log('✅ 已复制 account.js');
+			} catch (err) {
+				console.error('❌ 默认 account.js 不存在或复制失败:', err.message);
+			}
+		}
+
+		// 检查并拷贝 templates/account 目录
+		try {
+			await fsPromises.access(userTemplatesAccount, constants.F_OK);
+		} catch {
+			console.log('检测到 account=true 但缺少 templates/account 目录,正在从包内复制...');
+			const pkgTemplatesDir = path.join(__dirname, templatesDir),
+				defaultTemplatesAccount = path.join(pkgTemplatesDir, accountDir);
+			try {
+				await fsPromises.access(defaultTemplatesAccount, constants.F_OK);
+				await copyDir(defaultTemplatesAccount, userTemplatesAccount);
+				console.log('✅ 已复制 templates/account 目录');
+			} catch (err) {
+				console.error('❌ 默认 templates/account 目录不存在或复制失败:', err.message);
+			}
+		}
+	},
+
+	// ==================== 2.服务器配置与端口管理 ====================
+	/**
+	 * 解析并验证端口值
+	 * @param {string|number} portValue - 端口值
+	 * @param {string} source - 来源描述（用于错误消息）
+	 * @returns {number} 有效的端口号或默认值
+	 */
+	parseAndValidatePort = (portValue, source) => {
+		const portNum = parseInt(portValue);
+
+		// 检查是否为有效数字且在有效端口范围内 (1-65535)
+		if (!isNaN(portNum) && portNum > 0 && portNum < 65536) return portNum;
+		console.warn(`警告: ${source} "${portValue}" 无效,已启用默认端口:${defaultPort}`);
+		return defaultPort;
+	},
+
+	/**
+	 * 统一服务器配置解析函数
+	 *
+	 * 配置解析优先级：
+	 *  端口：
+	 *    1. 命令行参数 (--port 或 -p)
+	 *    2. 函数参数 (options.port)
+	 *    3. 环境变量 (process.env.PORT)
+	 *    4. 默认值 (常量 defaultPort)
+	 *
+	 *  热重载：
+	 *    1. 命令行参数 (--hot-reload/--no-hot-reload)
+	 *    2. 函数参数 (options.hotReload)
+	 *	  3. 环境变量 (process.env.HOTRELOAD)
+	 *    4. 默认值 (true)
+	 *
+	 *  登录模式：
+	 *    1. 命令行参数 (--account/--no-account)
+	 *    2. 函数参数 (options.account)
+	 *    3. 环境变量 (process.env.ACCOUNT)
+	 *    4. 默认值 (false)
+	 */
+	parseServerConfig = (options = {}) => {
+		let port, hotReload, account;
+		// 解析端口参数 - 优先级: 命令行 > 函数参数 > 环境变量 > 默认值
+		const args = process.argv.slice(2), portArgIndex = args.findIndex(arg => arg === '--port' || arg === '-p'),
+			portArgValue = portArgIndex !== -1 ? args[portArgIndex + 1] : null, { port: P, hotReload: H, account: A } = options;
+
+		if (portArgValue) port = parseAndValidatePort(portArgValue, '命令行参数');
+		else if (P !== undefined) port = parseAndValidatePort(P, '函数参数');
+		else if (process.env.PORT) port = parseAndValidatePort(process.env.PORT, '环境变量 PORT');
+		else port = defaultPort; // 默认端口
+
+		// 解析热重载参数 - 优先级: 命令行 > 函数参数 >  环境变量> 默认值
+		if (args.includes('--hot-reload')) hotReload = true;
+		else if (args.includes('--no-hot-reload')) hotReload = false;
+		else if (H !== undefined) hotReload = H;
+		else if (process.env.HOTRELOAD) hotReload = process.env.HOTRELOAD === 'true';
+		else hotReload = true; // 默认启用
+
+		// 解析登录模式参数 - 优先级: 命令行 > 函数参数 > 环境变量 > 默认值
+		if (args.includes('--account')) account = true;
+		else if (args.includes('--no-account')) account = false;
+		else if (A !== undefined) account = A;
+		else if (process.env.ACCOUNT) account = process.env.ACCOUNT === 'true';
+		else account = false; // 默认关闭
+
+		return { port, hotReload, account };
+	};
+
+// ==================== 3.全局CORS中间件和静态资源配置 ====================
+app.use((req, res, next) => {
+	// 基本CORS头
+	res.setHeader('Access-Control-Allow-Origin', '*');
+	res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD');
+	res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-Requested-With, Accept, Origin, X-CSRF-Token');
+	res.setHeader('Access-Control-Expose-Headers', 'Content-Length, Content-Range');
+	res.setHeader('Access-Control-Max-Age', '86400'); // 预检请求缓存24小时
+	res.setHeader('X-Content-Type-Options', 'nosniff');
+	res.setHeader('X-Frame-Options', 'SAMEORIGIN');
+	res.setHeader('Content-Security-Policy', "frame-ancestors 'self'");
+	// res.setHeader('Access-Control-Allow-Credentials', 'true');// 是否启用凭据（cookies、认证等）
+
+	// 处理预检请求（OPTIONS）
+	if (req.method === 'OPTIONS') {
+		res.setHeader('Content-Length', '0');
+		return res.status(204).end();
+	}
+
+	next();
+}), app.set('trust proxy', false);
+app.use('/static', express.static(staticAbsDir));
+
+// ==================== 4.服务器生命周期管理 ====================
+/**
+ * 控制台输出可访问页面信息
+ * @param {string[]} pages - 有效的模板文件名集合
+ * @param {number} port - 服务器端口号
+ * @param {boolean} hotReload - 是否启用热重载
+ */
+const printAvailablePages = (pages, port, hotReload) => {
+	console.log(`开发服务器启动成功!\n访问地址: http://localhost:${port}`);
+	if (hotReload) console.log(`✅ 热重载功能已启用(监听目录->${templatesAbsDir},${staticDir},${customizeDir})`);
+
+	console.log('\n可访问页面:');
+	pages.sort().forEach(page => {
+		const { url, encodedUrl, needsEncoding } = generateUrls(page, port);
+
+		if (needsEncoding) console.log(`  原始路径: ${url} (需复制访问)\n  编码路径: ${encodedUrl} (直接访问)`);
+		else console.log(`  直接访问: ${url}`);
+	});
+
+	console.log(`\n共发现 ${pages.length} 个可用模板`), console.log('-----------------------------------');
+}
+
+/**
+ * 服务器启动主函数
+ * >查看定义:@see {@link startServer}
+ * @async
+ * @param {Object} [options] - 配置对象
+ * @param {number} [options.port] - 可选端口号
+ * @param {boolean} [options.hotReload] - 是否启用热重载
+ * @param {boolean} [options.account] - 是否启用登录模式
+ */
+const startServer = async (options = {}) => {
+	try {
+		const config = parseServerConfig(options), { port: p, hotReload: h, account: acc } = config;
+
+		if (acc) await ensureAccountFiles(); 									  // 如果启用登录模式,验证必要文件
+		await loadUserFeatures(app), cachedPages = await getAvailableTemplates(); // 加载用户自定义功能获取模板内容
+
+		// 添加核心模板渲染中间件
+		app.use(async (req, res, next) => {
+			try {
+				const decodedPath = decodeURIComponent(req.path);
+				if (decodedPath === '/') {
+					const entryFile = await findEntryFile(cachedPages);
+					return res.redirect(`/${entryFile}`);
+				}
+
+				const templateFile = decodedPath.endsWith('.html') ? decodedPath.slice(1) : `${decodedPath.slice(1)}.html`;
+				if (cachedPages.includes(templateFile)) {
+					let rendered = await renderTemplate(templateFile);
+					rendered = await processIncludes(rendered, templateFile);
+					rendered = processVariables(rendered, { currentUrl: decodedPath, query: req.query ? JSON.stringify(req.query) : '' });
+
+					if (io) rendered = injectScript(rendered); // 如果启用了热重载,注入客户端脚本
+					return res.type('html').send(rendered);
+				}
+
+				next();
+			} catch (error) {
+				console.error(`处理请求时出错: ${error.message}`), console.error(error.stack);
+				next(error);
+			}
+		});
+		for (const page of cachedPages) await validateTemplateFile(page, true); // 验证模板文件
+
+		if (h) setupHotReload();
+		printAvailablePages(cachedPages, p, h), createServerWithSocket(app, h);
+
+		server.listen(p, () => {
+			console.log(`服务器运行中，按 Ctrl+C 退出`), console.log('-----------------------------------');
+		});
+
+		return p;
+	} catch (error) {
+		console.error('服务器启动失败:', error.message), process.exit(1);
+	}
+},
+
+	// ==================== 6.热重载功能实现 ====================
+	/**
+	 * 设置文件监听和热重载功能
+	 */
+	setupHotReload = () => {
+		// 监听模板目录、静态文件目录和后端目录
+		const watchDirs = [templatesAbsDir, staticAbsDir, customizeAbsDir].filter(dir => existsSync(dir));
+		if (watchDirs.length === 0) return console.warn('[热重载] 没有可监听的目录');
+
+		unmountMonitor = monitorFileWrites(); // 启用持续文件写入监控并获取卸载函数
+		// 文件变更事件处理函数
+		const handleFileEvent = (event, filePath) => {
+			const normalizedPath = path.normalize(filePath);
+			if (writtenFilesToIgnore.includes(normalizedPath)) return; // 忽略文件
+
+			const isBackendFile = filePath.startsWith(customizeAbsDir);
+			if (isBackendFile) {
+				console.log(`检测到${event}了${normalizedPath}后端文件,[热重载] 执行服务器重启并刷新页面...`);
+				io.emit('hot-reload', 3500), setTimeout(() => restartServer(), 500); // 通知浏览器延迟刷新,延迟后重启服务器
+			}
+			else {
+				console.log(`检测到${event}了${normalizedPath}前端文件,[热重载] 已刷新页面...`);
+				// 如果删除了HTML模板文件，从缓存中移除
+				if (event === '删除' && filePath.startsWith(templatesAbsDir) && filePath.endsWith('.html')) {
+					const templateName = path.relative(templatesAbsDir, filePath).replace(/\\/g, '/');
+					cachedPages = cachedPages.filter(page => page !== templateName);
+				}
+
+				io.emit('hot-reload', 100);   // 通知浏览器刷新
+			}
+		};
+
+		// 设置监听器(忽略隐藏文件)
+		watcher = chokidar.watch(watchDirs, {
+			ignored: /(^|[\/\\])\../, persistent: true, ignoreInitial: true
+		});
+
+		watcher.on('change', (filePath) => handleFileEvent('更改', filePath))
+			.on('add', (filePath) => handleFileEvent('添加', filePath))
+			.on('unlink', (filePath) => handleFileEvent('删除', filePath))
+			.on('error', (error) => console.error('[热重载] 文件监听错误:', error));
+	},
+
+	/**
+	 * 重启服务器
+	 */
+	restartServer = async () => {
+		try {
+			const port = server.address().port;
+			cleanupResources();
+			server.close(async () => {
+				// ✅ 重新加载所有自定义功能(强制破坏缓存),重新获取模板列表,重建服务器并设置热重载
+				await loadUserFeatures(app, false, true), cachedPages = await getAvailableTemplates();
+				createServerWithSocket(app, true), server.listen(port, () => setupHotReload());
+			});
+		} catch (error) {
+			console.error('[热重载] 重启过程中发生错误:', error);
+		}
+	};
+
+// ==================== 7.导出接口与启动执行 ====================
+export { startServer };
+if (process.argv[1] === __filename) startServer().catch(error => (console.error('服务器启动失败:', error), process.exit(1)));

package/dev.js

@@ -0,0 +1,4 @@
+import { startDevServer } from '@flun/html-template';
+
+// 启动开发服务器
+startDevServer({ port: 7296, hotReload: true, account: false }); // 默认参数:开发服务器端口7296,启用热更新,不启用登录系统;

package/f-CHANGELOG.md

@@ -0,0 +1,4 @@
+# 变更日志
+## [4.0.10] - 2026-04-30 10:30
+### 新包名更新完成通知:
+- 新包名的版本号将延续旧包包版本号;