@flun/html-template 4.4.2 → 5.0.0

package/customize/account.js

@@ -29,9 +29,7 @@ if (!env.MAIL_HOST || !env.MAIL_USER || !env.MAIL_PWD)
 
 // 邮件发送配置
 const transporter = createTransport({
-    host: env.MAIL_HOST,
-    port: env.MAIL_PORT,
-    secure: true,
+    host: env.MAIL_HOST, port: env.MAIL_PORT, secure: true,
     auth: { user: env.MAIL_USER, pass: env.MAIL_PWD }
 }),
     // ========== 辅助函数 ==========
@@ -51,10 +49,10 @@ const transporter = createTransport({
             emailVerified, emailVerificationToken: null,
             passwordResetToken: null, passwordResetExpires: null,
             twoFactorSecret: null, twoFactorEnabled: false,
-            backupCodes: [],
             webauthnCredentials: [], webauthnEnabled: false,
             createdAt: now, updatedAt: now, passwordChangedAt: now,
-            pendingEmail: null, pendingEmailToken: null, pendingEmailExpires: null
+            pendingEmail: null, pendingEmailToken: null, pendingEmailExpires: null,
+            backupCodes: [], codeFailures: 0, codeLockUntil: null
         };
     },
     initAdminUser = () => {
@@ -66,7 +64,7 @@ const transporter = createTransport({
         }
     },
     sendEmail = async (to, subject, html) => {
-        if (transporter) await transporter.sendMail({ from: `"Your App" <${env.MAIL_USER}>`, to, subject, html });
+        if (transporter) await transporter.sendMail({ from: `"我的网站" <${env.MAIL_USER}>`, to, subject, html });
         else console.log(`\n--- 模拟邮件 ---\n收件人: ${to}\n主题: ${subject}\n内容:\n${html}\n---`);
     },
     validateEmail = email => mailRegex.test(email), generateToken = () => randomBytes(32).toString('hex'),
@@ -132,13 +130,17 @@ const transporter = createTransport({
                 subject = '添加验证硬件通知';
                 actionDescription = '添加了一台新的硬件验证设备';
                 break;
+            case 'backup_code_lock':  // 新增：备份码锁定
+                subject = '安全警报：账户临时锁定';
+                actionDescription = '连续多次输入错误的备用码,账户已被临时锁定24小时';
+                break;
             default: return;
         }
 
         const html = `
-            <p>您好!</p>
-            <p>您的账户(${user.username})于 <strong>${now}</strong>在 <strong>${clientIp}</strong> 成功${actionDescription};</p>
-            <p>如果是您本人操作,请忽略此邮件,否则请立即处理;</p>
+            <p>主人好!</p>
+            <p>网站账户(${user.username})于 <strong>${now}</strong>在 <strong>${clientIp}</strong> ${actionDescription};</p>
+            <p>如果是您的操作,请忽略此邮件,否则请前往处理;</p>
             <p style="margin-left:65%;">此致<br/>&emsp;&nbsp;安全中心</p>
         `;
         await sendEmail(user.email, subject, html);
@@ -180,16 +182,14 @@ export const accountRouter = app => {
         set(sid, session, cb) {
             const file = path.join(this.sessionsDir, `${sid}.json`);
             try {
-                fs.writeFileSync(file, JSON.stringify(session));
-                cb(null);
+                fs.writeFileSync(file, JSON.stringify(session)), cb(null);
             } catch (e) { cb(e); }
         }
 
         destroy(sid, cb) {
             const file = path.join(this.sessionsDir, `${sid}.json`);
             try {
-                if (fs.existsSync(file)) fs.unlinkSync(file);
-                cb(null);
+                if (fs.existsSync(file)) fs.unlinkSync(file), cb(null);
             } catch (e) { cb(e); }
         }
 
@@ -225,11 +225,9 @@ export const accountRouter = app => {
     app.use(session({
         secret: env.SESSION_SECRET || 'dev-secret-change-in-production',
         store: sessionStore,
-        resave: false,
-        saveUninitialized: false,
+        resave: false, saveUninitialized: false,
         cookie: { secure: false, httpOnly: true, sameSite: 'lax', maxAge: 30 * 24 * oneHour }
     }));
-
     app.use(express.json(), express.urlencoded({ extended: true })), initAdminUser();
 
     // 2. 全局登录保护中间件
@@ -260,9 +258,7 @@ export const accountRouter = app => {
             const sessionLoginTime = req.session.loginTime || 0;
             if (user.passwordChangedAt > sessionLoginTime) {
                 req.session.destroy(() => {
-                    if (req.path.startsWith('/api/')) {
-                        return res.status(401).json({ message: '密码已修改,请重新登录' });
-                    }
+                    if (req.path.startsWith('/api/')) return res.status(401).json({ message: '密码已修改,请重新登录' });
                     return res.redirect('/login');
                 });
                 return;
@@ -281,7 +277,7 @@ export const accountRouter = app => {
     }, oneHour);
 
     // 定义安全限制和所有页面(公共页面 + 受保护页面)
-    const authLimiter = rateLimit({ windowMs: fifteenMin, max: 50, message: { message: '尝试次数过多，请稍后再试' } }),
+    const authLimiter = rateLimit({ windowMs: fifteenMin, max: 15, message: { message: '尝试次数过多,请稍后再试' } }),
         allPages = [...publicPage, '/profile'];
     allPages.forEach(page => {
         app.get(page, (req, res) => {
@@ -306,8 +302,7 @@ export const accountRouter = app => {
     // ========== 公开认证API ==========
     app.post('/api/register', authLimiter, async (req, res) => {
         const { username, email, password } = req.body;
-        if (!hasAllFields(req.body, ['username', 'email', 'password']))
-            return res.status(400).json({ message: '所有字段必填' });
+        if (!hasAllFields(req.body, ['username', 'email', 'password'])) return res.status(400).json({ message: '所有字段必填' });
         if (!validateEmail(email)) return res.status(400).json({ message: '邮箱格式不正确' });
         if (!validatePasswordLength(password)) return res.status(400).json({ message: '密码至少6位' });
 
@@ -354,12 +349,15 @@ export const accountRouter = app => {
         const valid = await verifyPassword(password, user.password);
         if (!valid) return res.status(401).json({ message: '用户名/邮箱或密码错误' });
         if (!user.emailVerified) return res.status(403).json({ message: '请先验证邮箱', needsVerification: true });
-        if (user.webauthnEnabled && user.webauthnCredentials.length > 0)
-            return req.session.tempUserId = user.id, res.json({ requireWebAuthn: true });
-        if (user.twoFactorEnabled) return req.session.tempUserId = user.id, res.json({ require2FA: true });
 
+        req.session.tempUserId = user.id; // 保存临时用户ID,供后续多因素验证使用
+        if (user.webauthnEnabled && user.webauthnCredentials.length > 0) return res.json({ requireWebAuthn: true });
+        if (user.twoFactorEnabled) return res.json({ require2FA: true });
+
+        // 没有多因素认证,直接登录
         req.session.userId = user.id, req.session.username = user.username, req.session.loginTime = Date.now();
-        recentPasswordResets.delete(user.email), res.json({ success: true, message: '登录成功' });
+        delete req.session.tempUserId, recentPasswordResets.delete(user.email);
+        res.json({ success: true, message: '登录成功' });
     });
 
     app.post('/api/verify-2fa', authLimiter, async (req, res) => {
@@ -370,25 +368,59 @@ export const accountRouter = app => {
         if (!tempUserId) return res.status(401).json({ message: '请先完成第一步登录' });
 
         const users = readUsers(), user = users.find(u => u.id === tempUserId);
-        if (!user?.twoFactorEnabled) return res.status(400).json({ message: '用户未启用2FA' });
+        if (!user?.twoFactorEnabled && !user?.webauthnEnabled)
+            return res.status(400).json({ message: '用户未启用多因素认证' });
+
+        // 过期锁定自动清除
+        if (user.codeLockUntil && user.codeLockUntil <= Date.now())
+            user.codeLockUntil = null, user.codeFailures = 0, touchAndSaveUser(users, user);
+        else if (user.codeLockUntil && user.codeLockUntil > Date.now())
+            return res.status(401).json({ message: '账户已被临时锁定,请24小时后重试', locked: true });
+
+        const { twoFactorSecret, backupCodes } = user;
+        let verified = false, backupValid = false;
+
+        // TOTP 验证（6位）
+        if (token.length === 6) {
+            try {
+                verified = await verifyTotp(twoFactorSecret, token);
+            } catch (err) {
+                console.error('TOTP 验证异常:', err.message);
+            }
+        }
 
-        const { twoFactorSecret, backupCodes } = user, verified = await verifyTotp(twoFactorSecret, token);
-        let backupValid = false;
-        if (!verified && backupCodes?.length)
+        // 备份码验证（长度:10位）
+        if (!verified && backupCodes?.length) {
             for (let i = 0; i < backupCodes.length; i++) {
                 const match = await verifyPassword(token, backupCodes[i]);
                 if (match) {
-                    backupValid = true, backupCodes.splice(i, 1), touchAndSaveUser(users, user);
+                    backupValid = true, backupCodes.splice(i, 1);
                     break;
                 }
             }
+        }
 
+        // 输入错误失败计数与锁定
+        if (!verified && !backupValid) {
+            user.codeFailures = (user.codeFailures || 0) + 1;
+            if (user.codeFailures >= 9) {
+                user.codeLockUntil = Date.now() + 24 * oneHour;
+                await sendSecurityAlertEmail(req, user, 'backup_code_lock'), touchAndSaveUser(users, user);
+                return res.status(401).json({ message: '输入错误次数过多,账户已被锁定24小时,请隔天重试或联系管理员', locked: true });
+            } else {
+                const remaining = 9 - user.codeFailures;
+                touchAndSaveUser(users, user);
+                return res.status(401).json({ message: `输入错误,剩余尝试次数:${remaining}`, remainingAttempts: remaining });
+            }
+        }
+
+        // 验证成功,重置所有限制
         if (verified || backupValid) {
-            delete req.session.tempUserId, req.session.userId = user.id, req.session.username = user.username;
-            req.session.loginTime = Date.now(), recentPasswordResets.delete(user.email);
-            res.json({ success: true, message: '2FA验证成功' });
+            user.codeFailures = 0, user.codeLockUntil = null, delete req.session.tempUserId;
+            req.session.userId = user.id, req.session.username = user.username, req.session.loginTime = Date.now();
+            recentPasswordResets.delete(user.email), touchAndSaveUser(users, user);
+            return res.json({ success: true, message: '二次验证成功' });
         }
-        else res.status(401).json({ message: '验证码无效' });
     });
 
     app.post('/api/logout', (req, res) => {
@@ -452,10 +484,10 @@ export const accountRouter = app => {
         const result = getCurrentUser(req);
         if (!result) return res.status(404).json({ message: '用户不存在' });
         const { id, username, email, emailVerified, twoFactorEnabled, createdAt, pendingEmail, webauthnEnabled,
-            webauthnCredentials } = result.user;
+            webauthnCredentials, backupCodes } = result.user;
         res.json({
             id, username, email, emailVerified, twoFactorEnabled, createdAt, pendingEmail, webauthnEnabled,
-            webauthnCredentials
+            webauthnCredentials, hasBackupCodes: !!(backupCodes?.length > 0)
         });
     });
 
@@ -523,7 +555,7 @@ export const accountRouter = app => {
         if (!result) return res.status(404).json({ message: '用户不存在' });
 
         const { user, users } = result, secret = generateSecret({ length: 32 }), otpauth_url = generateURI({
-            issuer: 'YourApp', label: user.username, secret,
+            issuer: '我的网站', label: user.username, secret,
         }), qrCodeUrl = await toDataURL(otpauth_url);
 
         user.twoFactorSecret = secret, touchAndSaveUser(users, user), res.json({ secret, qrCode: qrCodeUrl });
@@ -539,8 +571,14 @@ export const accountRouter = app => {
         const { user, users } = result, verified = await verifyTotp(user.twoFactorSecret, token);
         if (!verified) return res.status(400).json({ message: '验证码错误' });
 
-        const { plainCodes, hashedCodes } = generateBackupCodes();
-        user.backupCodes = hashedCodes, user.twoFactorEnabled = true, touchAndSaveUser(users, user);
+        let plainCodes = null;
+        // 仅当用户当前没有备份码时,生成一组新的
+        if (!user.backupCodes || user.backupCodes.length === 0) {
+            const { plainCodes: newPlain, hashedCodes } = generateBackupCodes();
+            user.backupCodes = hashedCodes, plainCodes = newPlain;;
+        }
+
+        user.twoFactorEnabled = true, touchAndSaveUser(users, user);
         res.json({ success: true, backupCodes: plainCodes, message: '2FA 已启用' });
     });
 
@@ -549,20 +587,26 @@ export const accountRouter = app => {
         if (!result) return res.status(404).json({ message: '用户不存在' });
 
         const { user, users } = result;
-        user.twoFactorEnabled = false, user.twoFactorSecret = null, user.backupCodes = [];
-        touchAndSaveUser(users, user), res.json({ success: true });
+        user.twoFactorEnabled = false, user.twoFactorSecret = null, touchAndSaveUser(users, user), res.json({ success: true });
     });
 
     app.post('/api/regenerate-backup-codes', async (req, res) => {
         const result = getCurrentUser(req);
         if (!result) return res.status(404).json({ message: '用户不存在' });
         const { user, users } = result;
-        if (!user.twoFactorEnabled) return res.status(400).json({ message: '2FA未启用' });
+        if (!user.twoFactorEnabled && !user.webauthnEnabled) return res.status(400).json({ message: '未启用任何多因素认证' });
 
         const { plainCodes, hashedCodes } = generateBackupCodes();
         user.backupCodes = hashedCodes, touchAndSaveUser(users, user), res.json({ backupCodes: plainCodes });
     });
 
+    app.post('/api/delete-backup-codes', async (req, res) => {
+        const result = getCurrentUser(req);
+        if (!result) return res.status(401).json({ message: '未登录' });
+        const { user, users } = result;
+        user.backupCodes = [], touchAndSaveUser(users, user), res.json({ success: true, message: '备份码已删除' });
+    });
+
     // ========== WebAuthn 硬件验证 API ==========
     app.post('/api/webauthn/register/begin', authLimiter, async (req, res) => {
         try {
@@ -570,20 +614,18 @@ export const accountRouter = app => {
             if (!result) return res.status(401).json({ message: '未登录' });
             const { id, username, webauthnCredentials } = result.user, rpID = getRpId(req),
                 options = await generateRegistrationOptions({
-                    rpName: 'Your App',
+                    rpName: '我的网站',
                     rpID, userID: Buffer.from(String(id)),
                     userName: username, userDisplayName: username,
                     attestationType: 'none',
                     excludeCredentials: webauthnCredentials.map(cred => ({
-                        id: cred.id,
-                        type: 'public-key',
-                        transports: cred.transports
+                        id: cred.id, type: 'public-key', transports: cred.transports
                     })),
                     authenticatorSelection: { userVerification: 'preferred' },
                 });
             req.session.webauthnRegisterChallenge = options.challenge, res.json(options);
         } catch (err) {
-            return res.status(400).json({ message: err.message || '硬件验证初始化失败,请确保使用 HTTPS 或 localhost 访问;' });
+            return res.status(400).json({ message: err.message });
         }
     });
 
@@ -615,18 +657,27 @@ export const accountRouter = app => {
 
         const clientIp = getClientIp(req), { id, publicKey, counter, transports = [], deviceType, backedUp } = cred,
             newCredential = {
-                id,
-                publicKey: fromBuffer(publicKey),
-                counter: Number(counter),
+                id, publicKey: fromBuffer(publicKey), counter: Number(counter),
                 transports, deviceType, backedUp,
                 deviceName: clientIp, createdAt: Date.now()
             };
 
         result.user.webauthnCredentials.push(newCredential);
         if (!result.user.webauthnEnabled) result.user.webauthnEnabled = true;
+
+        // 如果用户还没有备份码且至少启用了一个多因素认证,则自动生成备份码
+        let newBackupCodes = null;
+        if ((!result.user.backupCodes || result.user.backupCodes.length === 0) && !result.user.twoFactorEnabled) {
+            const { plainCodes, hashedCodes } = generateBackupCodes();
+            result.user.backupCodes = hashedCodes, newBackupCodes = plainCodes;
+        }
+
         touchAndSaveUser(result.users, result.user), delete req.session.webauthnRegisterChallenge;
         await sendSecurityAlertEmail(req, result.user, 'webauthn_added');
-        res.json({ success: true, credentials: result.user.webauthnCredentials });
+
+        const responseData = { success: true, credentials: result.user.webauthnCredentials };
+        if (newBackupCodes) responseData.backupCodes = newBackupCodes;
+        res.json(responseData);
     });
 
     // 获取用户凭证列表
@@ -643,26 +694,38 @@ export const accountRouter = app => {
 
         const result = getCurrentUser(req);
         if (!result) return res.status(401).json({ message: '未登录' });
-        if (!result.user) return res.status(500).json({ message: '用户数据异常' });
 
-        const credentials = result.user.webauthnCredentials ?? [], index = credentials.findIndex(c => c.id === credentialId);
+        const { user, users } = result, credentials = user.webauthnCredentials ?? [],
+            index = credentials.findIndex(c => c.id === credentialId);
+
         if (index === -1) return res.status(404).json({ message: '凭证不存在' });
+        credentials.splice(index, 1), user.webauthnCredentials = credentials;
 
-        credentials.splice(index, 1);
-        if (credentials.length === 0) result.user.webauthnEnabled = false;
-        result.user.webauthnCredentials = credentials;
-        touchAndSaveUser(result.users, result.user), res.json({ success: true, message: '设备已删除' });
+        // 如果没有凭证了,自动关闭硬件验证标志
+        if (credentials.length === 0) user.webauthnEnabled = false;
+        touchAndSaveUser(users, user), res.json({ success: true, message: '设备已删除' });
     });
 
     // 切换硬件验证启用状态
     app.post('/api/webauthn/toggle', authLimiter, async (req, res) => {
         const result = getCurrentUser(req);
         if (!result) return res.status(401).json({ message: '未登录' });
-        if (!result.user.webauthnEnabled && result.user.webauthnCredentials.length === 0)
+
+        const newState = !result.user.webauthnEnabled;
+        if (newState && result.user.webauthnCredentials.length === 0)
             return res.status(400).json({ message: '没有可用的硬件凭证,请先添加设备' });
 
-        result.user.webauthnEnabled = !result.user.webauthnEnabled, touchAndSaveUser(result.users, result.user);
-        res.json({ success: true, enabled: result.user.webauthnEnabled });
+        result.user.webauthnEnabled = newState;
+        let newBackupCodes = null;
+        if (newState && (!result.user.backupCodes || result.user.backupCodes.length === 0)) {
+            const { plainCodes, hashedCodes } = generateBackupCodes();
+            result.user.backupCodes = hashedCodes, newBackupCodes = plainCodes;
+        }
+
+        touchAndSaveUser(result.users, result.user);
+        const response = { success: true, enabled: result.user.webauthnEnabled };
+        if (newBackupCodes) response.backupCodes = newBackupCodes;
+        res.json(response);
     });
 
     // 开始硬件验证登录（生成断言选项）
@@ -678,9 +741,7 @@ export const accountRouter = app => {
                 options = await generateAuthenticationOptions({
                     rpID,
                     allowCredentials: user.webauthnCredentials.map(cred => ({
-                        id: cred.id,
-                        type: 'public-key',
-                        transports: cred.transports,
+                        id: cred.id, type: 'public-key', transports: cred.transports,
                     })),
                     userVerification: 'preferred', timeout: 60000,
                 });

package/dev-server.js

@@ -150,7 +150,7 @@ const printAvailablePages = (pages, port, hotReload, useHttps, host) => {
 
 	if (useHttps && (host === 'localhost' || host === '127.0.0.1')) {
 		console.warn('⚠️  警告: 使用 HTTPS 访问 localhost 会导致浏览器证书安全警告（自签名证书或证书域名不匹配）');
-		console.warn('   请使用 --host 参数指定与证书 CN/SAN 匹配的域名，例如: --host book.123xyz.cn');
+		console.warn('   请使用 --host 参数指定与证书 CN/SAN 匹配的域名，例如: --host www.abc.com');
 	}
 
 	console.log('\n可访问页面:');

package/f-CHANGELOG.md

@@ -1,10 +1,16 @@
 # 变更日志
+## [5.0.0] - 2026-06-10 10:05
+### 重大更新
+- 对templates/account目录中的页面结构进行了大面积优化,如果你是老用户请注意对比迁移!!!;
+> - 登录页面的具体二次验证统一由 zfa.html 处理;
+> - 新增登录二次验证错误次数限制,超出将锁定24小时;
+> - 备份码支持硬件使用;
+> - 备份码分离为独立卡片,将由启用2FA或添加硬件时判断是否存在智能生成,并保留了重新生成按钮;
+> > **更多细节请自行体验;**
+- customize\account.js文件为配合上述功能实现也做了相应适配;
+## [4.4.3] - 2026-06-05 22:16
+### 优化
+- 模板中用户页面的移动端样式适配;
 ## [4.4.2] - 2026-05-31 15:08
 ### 修复
-- 修复全局中间件中 `getCurrentUser(req)` 返回 `null` 时解构报错导致服务崩溃的问题,增加空值判断并自动清理无效登录态；
-## [4.4.1] - 2026-05-31 14:39
-### 优化
-- 删除了 customize/routes.js 文件中上一次优化造成的冗余路由;
-## [4.4.0] - 2026-05-31 14:25
-### 优化
-- 修改辅助功能(在线编辑css文件)中预览逻辑:删除单预览按钮,增加上、下、左、右和单页面预览按钮,及相关逻辑的全面优化,让体验更好;
+- 修复全局中间件中 `getCurrentUser(req)` 返回 `null` 时解构报错导致服务崩溃的问题,增加空值判断并自动清理无效登录态;

package/f-README.md

@@ -4,7 +4,7 @@
 
 - **推荐方式**：使用 `import` / `export` 语法,静态分析更友好,工具链兼容性最佳;
 - **兼容方式**：Node.js ≥ 23.5.0 原生支持 `require(esm)`；22.12+ 需开启 `--experimental-require-module` 标志;
-- **重要**：本文档所有示例均采用 **ESM 标准**，请确保你的项目 `package.json` 中已设置 `"type": "module"`，或将脚本后缀改为 `.mjs`;
+- **重要**：本文档所有示例均采用 **ESM 标准**,请确保你的项目 `package.json` 中已设置 `"type": "module"`,或将脚本后缀改为 `.mjs`;
 
 ---
 
@@ -80,7 +80,7 @@ npm i @flun/webauthn-server  # 身份验证服务后端处理
 npm i @flun/webauthn-browser # 身份验证前端处理
 # 所有家族包在支持 .d.ts 提示环境下,鼠标焦点包名都有丰富的导出和使用示例提示,再也不必到处翻找使用文档;建议在VScode环境下使用;
 ```
-> **重要提示**：初次使用最好在空项目中执行安装，安装过程会自动复制 ESM 示例和必要文件到根目录
+> **重要提示**：初次使用最好在空项目中执行安装,安装过程会自动复制 ESM 示例和必要文件到根目录
 
 ---
 
@@ -104,7 +104,7 @@ npm i @flun/webauthn-browser # 身份验证前端处理
 ```javascript
 import { startDevServer } from '@flun/html-template';
 startDevServer({ port: 7296, hotReload: true });
-// 如需启用 HTTPS，请参考下文“配置选项 → 启用 HTTPS”章节
+// 如需启用 HTTPS,请参考下文“配置选项 → 启用 HTTPS”章节
 ```
 
 **build.js（ESM）**
@@ -121,7 +121,7 @@ initProject({ mode: 'overwrite', verbose: true });
 
 然后使用：
 ```sh
-# 启动开发服务器（实时预览和热重载，默认不启用登录）
+# 启动开发服务器（实时预览和热重载,默认不启用登录）
 npm run dev
 
 # 启动开发服务器并启用登录系统
@@ -209,7 +209,7 @@ compile({ outputDir: 'dist' }); // 默认参数:目录名 dist;
 
 #### 方式二：使用自定义证书
 
-若已有证书文件（`.key` 和 `.crt`/`.pem`），直接指定路径：
+若已有证书文件（`.key` 和 `.crt`/`.pem`）,直接指定路径：
 
 ```javascript
 startDevServer({
@@ -230,9 +230,9 @@ node dev.js --https --https-key 你的私钥文件路径和文件名 --https-cer
 ```
 
 > **注意**：
-> - 使用 HTTPS 时，`host` 参数必须与证书中的域名（CN 或 SAN）完全一致。
-> - 若用 `localhost` 访问 HTTPS，浏览器会提示不安全，请按控制台警告改用正确的域名访问。
-> - 有关 `DnsAutoSSL.js` 的详细配置，请参考该文件内的注释或 `@flun/dns-auto-ssl` 文档。
+> - 使用 HTTPS 时,`host` 参数必须与证书中的域名（CN 或 SAN）完全一致;
+> - 若用 `localhost` 访问 HTTPS,浏览器会提示不安全,请按控制台警告改用正确的域名访问;
+> - 有关 `DnsAutoSSL.js` 的详细配置,请参考该文件内的注释或 `@flun/dns-auto-ssl` 文档;
 
 ## 模板标签使用指南
 
@@ -244,7 +244,7 @@ node dev.js --https --https-key 你的私钥文件路径和文件名 --https-cer
 ### 标签快捷输入方式
 **HBuilder用户**：
 1. 输入 `b!` 后按 Enter
-2. 输入标签名，自动创建开闭标签对
+2. 输入标签名,自动创建开闭标签对
 HBuilder自定义代码块配置(HTML和js)：
 ```json
 {
@@ -261,7 +261,7 @@ HBuilder自定义代码块配置(HTML和js)：
 ```
 **VS Code用户**：
 1. 安装 "html-custom-tags" 扩展
-2. 输入 `[!标签名]` 后按空格，自动输出 `[~标签名]`
+2. 输入 `[!标签名]` 后按空格,自动输出 `[~标签名]`
 ***并且其还支持大部分语言语法高亮,标签特殊高亮,标签统计,标签一键全复制等功能***
 
 ---
@@ -316,7 +316,7 @@ initProject({ mode: 'skip-files', verbose: true, account: false }); // 跳过已
 4. **开发调试**：使用 `node dev.js` 运行开发服务器
 5. **编译部署**：使用 `node build.js` 编译模板
 
-> **注意**：编译只会打包 `customize`、`static` 目录及文件，和编译模板生成的文件。根据是否有自定义路由，动态创建 `server.js` 入口文件。
+> **注意**：编译只会打包 `customize`、`static` 目录及文件,和编译模板生成的文件;根据是否有自定义路由,动态创建 `server.js` 入口文件;
 
 ---
 
@@ -487,7 +487,7 @@ export default {
 - 资源使用限制
 - 恶意代码拦截
 
-**用户无需额外配置**，所有安全防护在后台自动运行。
+**用户无需额外配置**,所有安全防护在后台自动运行;
 
 ### 💡 使用建议
 
@@ -509,19 +509,18 @@ export default {
 [include {{dynamicPath}}]
 ```
 
+---
 ### ⚠️ 重要提醒
 
-虽然我们提供了多重安全防护，但您仍需：
+虽然我们提供了多重安全防护,但您仍需：
 1. 谨慎处理用户输入数据
 2. 验证自定义函数的参数安全性
 3. 定期更新到最新版本
-
-> **安全是共同责任** - 我们负责引擎安全，您负责业务逻辑安全。
-
-这些防护措施确保您的模板渲染过程安全可靠，让您可以专注于业务开发。
+> 安装更新时不会覆盖根目录中已存在目录(customize,static和templates)
+> **安全是共同责任** - 我们负责引擎安全,您负责业务逻辑安全;
+这些防护措施确保您的模板渲染过程安全可靠,让您可以专注于业务开发;
 
 ---
-
 ## 故障排除
 
 ### 常见问题
@@ -529,16 +528,16 @@ export default {
 2. **区块不显示**：检查开闭标签名称是否一致
 3. **热重载失效**：确认修改的是模板或静态目录中的文件
 4. **路由不工作**：检查是否正确定义了 `setupRoutes` 导出
-5. **找不到函数**: 1. 检查函数名是否正确，2. 确认文件在 `customize` 目录内，3. 确认使用了 `export const functions = {...}` 语法
-6. **ESM 相关错误**：检查 `package.json` 是否包含 `"type": "module"`，或启动文件是否具有 `.mjs` 扩展名。
-7. **HTTPS 证书错误**：请确保 `host` 参数与证书中的域名完全匹配，且证书未被吊销或过期。开发环境可使用 `@flun/dns-auto-ssl` 自动生成受信任的证书。
+5. **找不到函数**: 1. 检查函数名是否正确,2. 确认文件在 `customize` 目录内,3. 确认使用了 `export const functions = {...}` 语法
+6. **ESM 相关错误**：检查 `package.json` 是否包含 `"type": "module"`,或启动文件是否具有 `.mjs` 扩展名;
+7. **HTTPS 证书错误**：请确保 `host` 参数与证书中的域名完全匹配,且证书未被吊销或过期;开发环境可使用 `@flun/dns-auto-ssl` 自动生成受信任的证书;
 
 ### 获取帮助
-如果遇到问题，可以：
+如果遇到问题,可以：
 1. 运行恢复初始文件脚本
 2. 检查浏览器控制台错误信息
 3. 确认文件路径和名称是否正确
 
 ---
 
-此模板工具包提供了从开发到生产的完整解决方案，适合各种规模的Web项目开发。
+此模板工具包提供了从开发到生产的完整解决方案,适合各种规模的Web项目开发;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flun/html-template",
-  "version": "4.4.2",
+  "version": "5.0.0",
   "description": "一个HTML模板工具包,提供开发服务器和模板编译功能,支持自定义标签和快捷输入,变量定义,包含文件引用,帮助开发者模块化处理HTML;",
   "main": "index.js",
   "types": "index.d.ts",