Hexo Solitude 的本地预览问题与解决方案

写在前面#

配置 Solitude 主题时，我遇到了个天大的问题。

Solitude 主题是支持 Hexo 内置的标签语法和 Solitude 的扩展标签。不过，扩展标签要装插件。

1
npm install hexo-solitude-tag --save

1
pnpm add hexo-solitude-tag

1
yarn add hexo-solitude-tag

很简单。具体的语法，请看官方文档。话说为什么是放在 demo 而不是文档啊

外挂标签使用 | Solitude

这篇文章介绍了外挂标签的使用。

但是，遇到了问题。

大问题#

正当我兴致十足，执行了 Hexo 三连，打开了 localhost:3000 后：

1
hexo cl && hexo g && hexo s

没想到，标签的样式竟然消失了！

NOTE
由于 Fuwari 暂不支持 Hexo 标签，这里可能无法正常渲染

本来这是个按钮：

{% button ‘fa-brands fa-github’ ‘我的GitHub’ ‘https://github.com/MSQY-H’ %}

结果变成了：

我的GitHub

那可难搞了。

解决方案#

经过与B大哥与D大哥两位好朋友的探讨研究后，我终于发现了问题。

问题在于 hexo s。它的生成机制与 hexo g 不同，可能内部会与插件产生冲突。

其实不止我一个人有这个问题，网上很多人在使用插件时也有类似问题。

手敲命令#

其实要解决这个问题很简单，只要分别输入：

1
hexo g
2
npx serve public

就可以了。（不一定要用 npx serve public，其他可以启动服务器的命令也可以）

其实原理非常简单：虽然 hexo s 实现机制太过复杂，可能会出现问题，但是 hexo g 不会有这个问题（要是问题还在，就检查一下代码或者给开发者提 issue 吧）

所以我们曲线救国：通过 hexo g 生成静态文件，再通过 npx serve public 启动本地服务器。

问题解决了，完美！

但是，这种方式有缺点：

没有文件监听，每次都要手动敲，太麻烦了！

万物皆可脚本#

~~因为懒~~为了让生活更方便，我 Vibe Coding了一下，和D大哥聊了 15 分钟，写了个脚本。

其实这个脚本核心逻辑是这样的：

使用 chokidar 监听文件变动
执行 hexo g --incremental
启动静态服务器

WARNING
以下脚本针对我的开发环境编写，不一定通用，并非官方方案，此脚本仅作参考，建议你自己 Vibe Coding。

WARNING
以下代码由 DeepSeek 编写

Node.js 版本：24.17.0
Yarn 版本：4.17.0
Hexo 版本：7.3.0
Solitude 版本：3.0.21

1
const { spawn, execSync } = require('child_process');
2
const fs = require('fs');
3
const path = require('path');
4
const os = require('os');
5
const chokidar = require('chokidar');
677 collapsed lines
6
const express = require('express');
7
const serveStatic = require('serve-static');
8

9
// ---------- 参数解析 ----------
10
let PORT = 3000;
11
let silent = false;
12
let quickMode = false;
13
let directServe = false;   // 新增：直接启动服务器，跳过首次构建
14

15
const args = process.argv.slice(2);
16
for (let i = 0; i < args.length; i++) {
17
  const arg = args[i];
18
  if (arg === '-h' || arg === '--help') {
19
    console.log(`
20
使用方法: node dev.js [端口] [选项]
21

22
选项:
23
  -s, --silent    静默模式，不输出 hexo 日志（错误除外）
24
  -q, --quick     快速模式，省略手动添加的延迟（防抖延迟除外）
25
  -d, --direct    直接启动服务器，跳过首次构建（适用于已生成 public 的情况）
26
  -h, --help      显示此帮助信息
27

28
示例:
29
  node dev.js 4000
30
  node dev.js -s 4000
31
  node dev.js -q -d
32
`);
33
    process.exit(0);
34
  } else if (arg === '-s' || arg === '--silent') {
35
    silent = true;
36
  } else if (arg === '-q' || arg === '--quick') {
37
    quickMode = true;
38
  } else if (arg === '-d' || arg === '--direct') {
39
    directServe = true;
40
  } else if (/^\d+$/.test(arg) && PORT === 3000) {
41
    PORT = parseInt(arg, 10);
42
  }
43
}
44

45
const CWD = process.cwd();
46
const PUBLIC_DIR = path.join(CWD, 'public');
47
const WATCH_PATHS = [
48
  'source',
49
  '_config.yml',
50
  'scaffolds',
51
  'themes',
52
  'package.json',
53
];
54

55
const DEBOUNCE_DELAY = 300;
56
const BAR_LENGTH = 20;
57
const BOUNCE_WIDTH = 3;
58
const FRAME_ACTIVE = 100;
59
const FRAME_IDLE = 500;
60
const FILL_STAY = quickMode ? 0 : 500;
61
const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
62

63
// ---------- 状态变量 ----------
64
let isBuilding = false;
65
let buildTimer = null;
66
let server = null;           // 存储 http.Server 实例
67
let watcher = null;
68
let lastBuildFailed = false;
69
let watcherReady = false;
70

71
let sliderWidth = BOUNCE_WIDTH;
72
let sliderPos = 0;
73
let dir = 1;
74
let progressMode = 'bounce';
75
let renderTimeout = null;
76
let spinnerIdx = 0;
77
let pendingLogs = [];
78
let currentBuildProcess = null;
79

80
let initializing = false;
81
let serverStarting = false;
82
let buildStartTime = 0;
83
let firstBuild = false;
84
let hexoErrorContext = false;  // 错误上下文标志
85

86
// ---------- 颜色常量 ----------
87
const RESET = '\x1b[0m';
88
const BG_BUILD = '\x1b[48;5;208m\x1b[30m';
89
const BG_RUN   = '\x1b[42m\x1b[37m';
90
const BG_FAIL  = '\x1b[41m\x1b[37m';
91
const BG_INIT  = '\x1b[44m\x1b[37m';
92

93
const LEVEL_COLORS = {
94
  INFO:  '\x1b[36m',
95
  WARN:  '\x1b[33m',
96
  ERROR: '\x1b[31m',
97
  HEXO_ERROR: '\x1b[31m',
98
  SUCCESS:'\x1b[32m',
99
  DEBUG: '\x1b[35m',
100
};
101

102
// ---------- 工具函数 ----------
103
function formatTime(seconds) {
104
  if (seconds >= 60) {
105
    const mins = Math.floor(seconds / 60);
106
    const secs = Math.floor(seconds % 60);
107
    return `${mins}m${secs}s`;
108
  }
109
  return `${seconds.toFixed(1)}s`;
110
}
111

112
function getProgressBar() {
113
  const bg = '-', fg = '#';
114
  if (progressMode === 'fill') return fg.repeat(BAR_LENGTH);
115
  const w = Math.round(sliderWidth);
116
  const pos = Math.round(sliderPos);
117
  let bar = '';
118
  for (let i = 0; i < BAR_LENGTH; i++) bar += (i >= pos && i < pos + w) ? fg : bg;
119
  return bar;
120
}
121

122
// ---------- 统一日志系统 ----------
123
function flushLogs() {
124
  if (!pendingLogs.length) return;
125
  const lines = [...pendingLogs];
126
  pendingLogs = [];
127
  process.stdout.write('\r\x1b[K');
128
  lines.forEach(l => console.log(l));
129
}
130

131
const YARN_PATTERN = /This project is configured to use yarn/i;
132

133
function outputLog(category, levelOrType, message, extra = {}) {
134
  if (category === 'hexo') {
135
    let line = message.trimEnd();
136
    if (!line || YARN_PATTERN.test(line)) return;
137

138
    const match = line.match(/^(INFO|WARN|ERROR|DEBUG)\s+(.*)/i);
139
    let level = 'INFO', msg = line;
140
    if (match) { level = match[1].toUpperCase(); msg = match[2]; }
141

142
    if (/\b(FATAL|YAMLException)\b/i.test(line)) {
143
      level = 'ERROR';
144
    }
145

146
    const isFatal = /\b(FATAL|YAMLException)\b/i.test(line);
147
    const isErrorDesc = /Error:\s/i.test(line);
148
    const isCodeLine = /^\s+\d+\s*\|/.test(line) || line.includes('---^');
149
    const isStackLine = /^\s+at\s/.test(line);
150
    const isError = (level === 'ERROR') || isFatal || isErrorDesc || isCodeLine || isStackLine;
151

152
    // 错误上下文管理
153
    if (isError) {
154
      hexoErrorContext = true;   // 进入错误上下文
155
    } else if (hexoErrorContext) {
156
      if (level === 'INFO' && !isError) {
157
        hexoErrorContext = false;
158
      } else if (level === 'DEBUG') {
159
        hexoErrorContext = false;
160
      } else if (level === 'WARN') {
161
        // 保留上下文
162
      }
163
    }
164

165
    if (silent && !isError && !hexoErrorContext) return;
166

167
    let prefixColor;
168
    if (level === 'INFO') prefixColor = LEVEL_COLORS.INFO;
169
    else if (level === 'DEBUG') prefixColor = LEVEL_COLORS.DEBUG;
170
    else prefixColor = LEVEL_COLORS.HEXO_ERROR;
171

172
    let bodyColor = '';
173
    if (level === 'ERROR' || isFatal || isErrorDesc) bodyColor = '\x1b[31m';
174
    else if (isCodeLine) bodyColor = '\x1b[34m';
175
    else if (isStackLine) bodyColor = '\x1b[33m';
176

177
    const prefix = ` ${prefixColor}│➤ [hexo] [${level}]${RESET}`;
178
    const body = bodyColor ? `${bodyColor}${msg}${RESET}` : msg;
179
    pendingLogs.push(`${prefix} ${body}`);
180

181
  } else if (category === 'dev') {
182
    process.stdout.write('\r\x1b[K');
183
    let prefix, body, color = '';
184
    const type = levelOrType;
185

186
    if (type === 'stepStart') {
187
      color = LEVEL_COLORS.INFO;
188
      prefix = ` ${color}┌➤ [dev] [INFO]${RESET}`;
189
      body = `${extra.emoji || '🚀'} ${message}`;
190
    } else if (type === 'stepMid') {
191
      color = LEVEL_COLORS.INFO;
192
      prefix = ` ${color}│➤ [dev] [INFO]${RESET}`;
193
      body = `📘 ${message}`;
194
    } else if (type === 'stepEndSuccess') {
195
      color = LEVEL_COLORS.SUCCESS;
196
      prefix = ` ${color}└➤ [dev] [SUCCESS]${RESET}`;
197
      body = `✨ ${message}`;
198
    } else if (type === 'stepEndFail') {
199
      color = LEVEL_COLORS.ERROR;
200
      prefix = ` ${color}└➤ [dev] [ERROR]${RESET}`;
201
      body = `❌ ${message}`;
202
    } else if (type === 'info') {
203
      color = LEVEL_COLORS.INFO;
204
      prefix = `  ➤ ${color}[dev] [INFO]${RESET}`;
205
      body = `📘 ${message}`;
206
    } else {
207
      prefix = `[dev]`;
208
      body = message;
209
    }
210
    console.log(`${prefix} ${body}`);
211
  }
212
}
213

214
function logHexoLine(line) { outputLog('hexo', null, line); }
215
function logStepStart(msg, emoji = '🚀') { outputLog('dev', 'stepStart', msg, { emoji }); }
216
function logStepMid(msg) { outputLog('dev', 'stepMid', msg); }
217
function logStepEndSuccess(msg) { outputLog('dev', 'stepEndSuccess', msg); }
218
function logStepEndFail(msg) { outputLog('dev', 'stepEndFail', msg); }
219
function devInfo(msg) { outputLog('dev', 'info', msg); }
220

221
function printShortcuts() {
222
  devInfo('快捷键: Ctrl+C 退出 | Ctrl+R 完整重建 | Ctrl+S 启动/重启服务器');
223
}
224

225
// ---------- 网络与服务器 ----------
226
function getLocalIP() {
227
  const nets = os.networkInterfaces();
228
  for (const name of Object.keys(nets)) {
229
    for (const net of nets[name]) {
230
      if (net.family === 'IPv4' && !net.internal) return net.address;
231
    }
232
  }
233
  return '127.0.0.1';
234
}
235

236
function startServer() {
237
  if (server || serverStarting) return;
238
  serverStarting = true;
239

240
  logStepStart('启动服务器');
241

242
  const delay = quickMode ? 0 : 1000;
243
  setTimeout(() => {
244
    const app = express();
245
    app.use(serveStatic(PUBLIC_DIR, { index: 'index.html', setHeaders: res => res.setHeader('Cache-Control', 'no-cache') }));
246
    app.use((req, res) => res.sendFile(path.join(PUBLIC_DIR, 'index.html')));
247

248
    const httpServer = app.listen(PORT, () => {
249
      serverStarting = false;
250
      server = httpServer;
251
      const localIP = getLocalIP();
252
      logStepMid(`本地访问: http://localhost:${PORT}`);
253
      logStepMid(`局域网访问: http://${localIP}:${PORT}`);
254
      if (watcher) logStepMid('文件监控已就绪');
255
      logStepEndSuccess('服务器已启动');
256
      printShortcuts();
257
      scheduleScroll();
258
    });
259

260
    httpServer.on('error', err => {
261
      serverStarting = false;
262
      logStepEndFail(`服务器错误: ${err.message}`);
263
    });
264
  }, delay);
265
}
266

267
// ---------- 文件监控 ----------
268
function startWatcher() {
269
  if (watcher) return;
270
  watcher = chokidar.watch(WATCH_PATHS, {
271
    ignoreInitial: true, persistent: true, cwd: CWD,
272
    ignored: [/(^|[\/\\])\../, /\.tmp$/i, /~$/, /\.sw[op]$/i, /\.bak$/i],
273
  });
274
  watcher.on('add', p => { scheduleBuild(`新增: ${p}`); devInfo(`新增文件: ${p}`); });
275
  watcher.on('change', p => { scheduleBuild(`变更: ${p}`); devInfo(`文件变化: ${p}`); });
276
  watcher.on('unlink', p => { scheduleBuild(`删除: ${p}`); devInfo(`文件删除: ${p}`); });
277
  watcher.on('ready', () => {
278
    watcherReady = true;
279
    // 如果服务器还未启动，则启动（直接模式下由外部调用）
280
    startServer();
281
  });
282
}
283

284
// ---------- 构建逻辑 ----------
285
function abortCurrentBuild() {
286
  if (currentBuildProcess) {
287
    devInfo('检测到新的变更，中止当前构建...');
288
    try { currentBuildProcess.kill('SIGTERM'); } catch (e) {}
289
    currentBuildProcess = null;
290
  }
291
}
292

293
function build(trigger) {
294
  if (buildTimer) { clearTimeout(buildTimer); buildTimer = null; }
295
  if (isBuilding) abortCurrentBuild();
296

297
  hexoErrorContext = false;
298
  isBuilding = true;
299
  lastBuildFailed = false;
300
  initializing = false;
301
  progressMode = 'bounce';
302
  sliderWidth = BOUNCE_WIDTH;
303
  sliderPos = 0;
304
  dir = 1;
305
  buildStartTime = Date.now();
306

307
  logStepStart(`构建开始 (${trigger})`);
308
  forceRender();
309
  currentBuildProcess = runHexo(['g', '--incremental']);
310
}
311

312
function fullRebuild() {
313
  if (isBuilding) abortCurrentBuild();
314

315
  hexoErrorContext = false;
316
  isBuilding = true;
317
  lastBuildFailed = false;
318
  initializing = false;
319
  progressMode = 'bounce';
320
  sliderWidth = BOUNCE_WIDTH;
321
  sliderPos = 0;
322
  dir = 1;
323
  const totalStart = Date.now();
324
  buildStartTime = totalStart;
325

326
  logStepStart('完整重建 - 清理 (hexo clean)');
327
  forceRender();
328

329
  const clean = spawn('hexo', ['clean'], { cwd: CWD, stdio: ['ignore','pipe','pipe'] });
330
  currentBuildProcess = clean;
331
  let cleanOut = '', cleanErr = '';
332
  clean.stdout.on('data', d => {
333
    cleanOut += d.toString();
334
    const lines = cleanOut.split('\n');
335
    cleanOut = lines.pop();
336
    lines.forEach(logHexoLine);
337
  });
338
  clean.stderr.on('data', d => {
339
    cleanErr += d.toString();
340
    const lines = cleanErr.split('\n');
341
    cleanErr = lines.pop();
342
    lines.forEach(logHexoLine);
343
  });
344

345
  clean.on('close', code => {
346
    if (cleanOut) logHexoLine(cleanOut);
347
    if (cleanErr) logHexoLine(cleanErr);
348
    if (currentBuildProcess !== clean) return;
349

350
    const cleanTime = (Date.now() - totalStart) / 1000;
351
    if (code !== 0) {
352
      isBuilding = false;
353
      lastBuildFailed = true;
354
      logStepEndFail(`清理失败 (${formatTime(cleanTime)})，重建中止`);
355
      currentBuildProcess = null;
356
      startFillThenScroll();
357
      return;
358
    }
359
    logStepEndSuccess(`清理完成 (${formatTime(cleanTime)})`);
360

361
    logStepStart('完整重建 - 生成 (hexo g)');
362
    const genStart = Date.now();
363
    currentBuildProcess = runHexo(['g'], {
364
      suppressEndLog: true,
365
      onClose: (genCode) => {
366
        const genTime = (Date.now() - genStart) / 1000;
367
        const totalTime = (Date.now() - totalStart) / 1000;
368
        if (genCode === 0) {
369
          logStepEndSuccess(`生成完成 (${formatTime(genTime)})`);
370
          logStepEndSuccess(`完整重建完成，总耗时 ${formatTime(totalTime)}`);
371
        } else {
372
          logStepEndFail(`生成失败 (${formatTime(genTime)})，退出码 ${genCode}`);
373
          logStepEndFail(`完整重建失败，总耗时 ${formatTime(totalTime)}`);
374
        }
375
      }
376
    });
377
  });
378

379
  clean.on('error', err => {
380
    if (currentBuildProcess !== clean) return;
381
    const cleanTime = (Date.now() - totalStart) / 1000;
382
    isBuilding = false;
383
    lastBuildFailed = true;
384
    logStepEndFail(`清理错误: ${err.message} (${formatTime(cleanTime)})`);
385
    currentBuildProcess = null;
386
    startFillThenScroll();
387
  });
388
}
389

390
function runHexo(args, opts = {}) {
391
  const { suppressEndLog = false, onClose } = opts;
392
  const child = spawn('hexo', args, { cwd: CWD, stdio: ['ignore','pipe','pipe'] });
393
  let outBuf = '', errBuf = '';
394

395
  child.stdout.on('data', d => {
396
    outBuf += d.toString();
397
    const lines = outBuf.split('\n');
398
    outBuf = lines.pop();
399
    lines.forEach(logHexoLine);
400
  });
401
  child.stderr.on('data', d => {
402
    errBuf += d.toString();
403
    const lines = errBuf.split('\n');
404
    errBuf = lines.pop();
405
    lines.forEach(logHexoLine);
406
  });
407

408
  child.on('close', code => {
409
    if (currentBuildProcess !== child) return;
410
    if (outBuf) logHexoLine(outBuf);
411
    if (errBuf) logHexoLine(errBuf);
412

413
    const elapsed = (Date.now() - buildStartTime) / 1000;
414
    isBuilding = false;
415
    lastBuildFailed = (code !== 0);
416
    currentBuildProcess = null;
417
    hexoErrorContext = false;
418

419
    if (!suppressEndLog) {
420
      if (code === 0) {
421
        logStepEndSuccess(`构建完成 (${formatTime(elapsed)})`);
422
      } else {
423
        logStepEndFail(`构建失败 (${formatTime(elapsed)})，退出码 ${code}`);
424
      }
425
    }
426

427
    if (firstBuild && code === 0) {
428
      firstBuild = false;
429
      startWatcher();
430
      startServer();
431
    } else if (firstBuild && code !== 0) {
432
      firstBuild = false;
433
      logStepEndFail('首次构建失败，退出');
434
      process.exit(1);
435
    }
436

437
    if (onClose) onClose(code);
438
    startFillThenScroll();
439
  });
440

441
  child.on('error', err => {
442
    if (currentBuildProcess !== child) return;
443
    const elapsed = (Date.now() - buildStartTime) / 1000;
444
    isBuilding = false;
445
    lastBuildFailed = true;
446
    currentBuildProcess = null;
447
    hexoErrorContext = false;
448

449
    if (!suppressEndLog) {
450
      logStepEndFail(`构建进程错误: ${err.message} (${formatTime(elapsed)})`);
451
    }
452
    if (firstBuild) {
453
      firstBuild = false;
454
      process.exit(1);
455
    }
456
    if (onClose) onClose(-1);
457
    startFillThenScroll();
458
  });
459

460
  return child;
461
}
462

463
// ---------- 进度动画控制 ----------
464
function startFillThenScroll() {
465
  if (progressMode === 'fill') return;
466
  sliderWidth = BAR_LENGTH;
467
  sliderPos = 0;
468
  progressMode = 'fill';
469
  if (FILL_STAY > 0) {
470
    setTimeout(() => {
471
      if (server && !isBuilding) {
472
        sliderWidth = BOUNCE_WIDTH;
473
        sliderPos = -sliderWidth;
474
        progressMode = 'scroll';
475
      }
476
    }, FILL_STAY);
477
  } else {
478
    if (server && !isBuilding) {
479
      sliderWidth = BOUNCE_WIDTH;
480
      sliderPos = -sliderWidth;
481
      progressMode = 'scroll';
482
    }
483
  }
484
}
485

486
function scheduleScroll() {
487
  if (!isBuilding && server && !serverStarting && progressMode !== 'scroll') {
488
    sliderWidth = BOUNCE_WIDTH;
489
    sliderPos = -sliderWidth;
490
    progressMode = 'scroll';
491
  }
492
}
493

494
function scheduleBuild(trigger) {
495
  if (buildTimer) clearTimeout(buildTimer);
496
  buildTimer = setTimeout(() => { buildTimer = null; build(trigger); }, DEBOUNCE_DELAY);
497
}
498

499
function forceRender() {
500
  if (renderTimeout) { clearTimeout(renderTimeout); renderTimeout = null; }
501
  renderLine();
502
  scheduleRender();
503
}
504

505
function scheduleRender() {
506
  if (renderTimeout) clearTimeout(renderTimeout);
507
  const active = initializing || isBuilding || serverStarting || progressMode === 'fill';
508
  const interval = active ? FRAME_ACTIVE : FRAME_IDLE;
509
  renderTimeout = setTimeout(() => {
510
    spinnerIdx++;
511
    renderLine();
512
    scheduleRender();
513
  }, interval);
514
}
515

516
// ---------- 状态栏渲染 ----------
517
function renderLine() {
518
  flushLogs();
519
  updateProgress();
520

521
  let bgStyle;
522
  if (initializing) {
523
    bgStyle = BG_INIT;
524
  } else if (isBuilding) {
525
    bgStyle = BG_BUILD;
526
  } else if (lastBuildFailed) {
527
    bgStyle = BG_FAIL;
528
  } else if (serverStarting || server) {
529
    bgStyle = BG_RUN;
530
  } else {
531
    bgStyle = RESET;
532
  }
533

534
  const spinner = isBuilding ? SPINNER_FRAMES[spinnerIdx % SPINNER_FRAMES.length] : ' ';
535
  const mark = (server && !serverStarting) ? '' : '[x]';
536
  let statusText;
537

538
  if (initializing) {
539
    statusText = `初始化中 ${mark}端口:${PORT}`;
540
  } else if (serverStarting) {
541
    statusText = `启动服务器中 ${mark}端口:${PORT}`;
542
  } else if (isBuilding) {
543
    const elapsed = buildStartTime ? (Date.now() - buildStartTime) / 1000 : 0;
544
    statusText = `构建中 ${formatTime(elapsed)} ${mark}端口:${PORT}`;
545
  } else if (lastBuildFailed) {
546
    statusText = `构建失败 ${mark}端口:${PORT}`;
547
  } else if (server) {
548
    statusText = `运行中 端口:${PORT}`;
549
  } else {
550
    statusText = `就绪 ${mark}端口:${PORT}`;
551
  }
552

553
  process.stdout.write(`\r\x1b[K${bgStyle} ${spinner} [${getProgressBar()}] ${statusText} ${RESET}`);
554
}
555

556
function updateProgress() {
557
  if (progressMode === 'bounce') {
558
    sliderPos += dir;
559
    if (sliderPos + sliderWidth >= BAR_LENGTH) { sliderPos = BAR_LENGTH - sliderWidth; dir = -1; }
560
    else if (sliderPos <= 0) { sliderPos = 0; dir = 1; }
561
  } else if (progressMode === 'scroll') {
562
    sliderPos += 1;
563
    if (sliderPos > BAR_LENGTH) sliderPos = -sliderWidth;
564
  }
565
}
566

567
// ---------- 欢迎语 ----------
568
function printWelcome() {
569
  flushLogs();
570
  console.log(`\x1b[36m✨ 欢迎使用LJXH的Hexo构建脚本 (∠・ω< )⌒☆！\x1b[0m`);
571
  console.log(`\x1b[90m⚡ Node.js:\x1b[0m ${process.version}`);
572

573
  let pm = 'npm', pmIcon = '📦';
574
  try {
575
    if (fs.existsSync(path.join(CWD, 'yarn.lock'))) { pm = 'yarn'; pmIcon = '🧶'; }
576
    else if (fs.existsSync(path.join(CWD, 'pnpm-lock.yaml'))) { pm = 'pnpm'; pmIcon = '📦'; }
577
    else {
578
      const pkg = JSON.parse(fs.readFileSync(path.join(CWD, 'package.json'), 'utf8'));
579
      if (pkg.packageManager && pkg.packageManager.includes('yarn')) { pm = 'yarn'; pmIcon = '🧶'; }
580
    }
581
    const pmVersion = execSync(`${pm} --version`, { encoding: 'utf8' }).trim();
582
    console.log(`${pmIcon} ${pm}: ${pmVersion}`);
583
  } catch {}
584

585
  try {
586
    const hexoVersion = require(path.join(CWD, 'node_modules/hexo/package.json')).version;
587
    console.log(`🌐 Hexo: ${hexoVersion}`);
588
  } catch {}
589

590
  try {
591
    const config = fs.readFileSync(path.join(CWD, '_config.yml'), 'utf8');
592
    const theme = config.match(/^theme:\s*(\S+)/m)?.[1];
593
    if (theme) console.log(`🎨 主题: ${theme}`);
594
  } catch {}
595
  console.log('');
596
  printShortcuts();
597
}
598

599
// ---------- Ctrl+S 重启服务器 ----------
600
function restartServer() {
601
  if (server) {
602
    devInfo('正在重启服务器...');
603
    server.close(() => {
604
      server = null;
605
      startServer();
606
    });
607
  } else {
608
    devInfo('正在启动服务器...');
609
    startServer();
610
  }
611
}
612

613
// ---------- 退出 ----------
614
function gracefulExit() {
615
  process.stdout.write(`\r\x1b[K${RESET}\n`);
616
  console.log('👋 感谢使用，下次见 (´• ω •`)ﾉ ♪');
617
  if (renderTimeout) clearTimeout(renderTimeout);
618
  if (server) server.close();
619
  if (watcher) watcher.close();
620
  if (process.stdin.isTTY) { process.stdin.setRawMode(false); process.stdin.pause(); }
621
  process.exit(0);
622
}
623

624
// ---------- 初始化 ----------
625
function init() {
626
  initializing = true;
627
  hexoErrorContext = false;
628
  scheduleRender();
629

630
  printWelcome();
631

632
  // 确保 public 目录存在（如果是直接启动而目录不存在，给出警告但不阻止启动）
633
  if (!fs.existsSync(PUBLIC_DIR)) {
634
    if (directServe) {
635
      devInfo('public 目录不存在，服务器可能返回 404，建议先执行 hexo generate');
636
    } else {
637
      fs.mkdirSync(PUBLIC_DIR, { recursive: true });
638
    }
639
  }
640

641
  const delay = quickMode ? 0 : 1000;
642
  setTimeout(() => {
643
    if (directServe) {
644
      // 直接启动模式：跳过首次构建，直接启动服务器和文件监控
645
      initializing = false;
646
      logStepStart('直接启动模式 (跳过构建)', '⚡');
647
      startWatcher();   // 启动监控（会内部调用 startServer）
648
      startServer();    // 确保服务器启动
649
      // 强制渲染一帧，让状态栏更新
650
      forceRender();
651
    } else {
652
      // 正常首次构建
653
      logStepStart('首次构建');
654
      firstBuild = true;
655
      isBuilding = true;
656
      lastBuildFailed = false;
657
      initializing = false;
658
      progressMode = 'bounce';
659
      sliderWidth = BOUNCE_WIDTH;
660
      sliderPos = 0;
661
      dir = 1;
662
      buildStartTime = Date.now();
663
      forceRender();
664
      currentBuildProcess = runHexo(['g', '--incremental']);
665
    }
666
  }, delay);
667

668
  if (process.stdin.isTTY) {
669
    process.stdin.setRawMode(true);
670
    process.stdin.resume();
671
    process.stdin.on('data', chunk => {
672
      if (chunk.length === 1) {
673
        if (chunk[0] === 3) gracefulExit();          // Ctrl+C
674
        else if (chunk[0] === 18) fullRebuild();     // Ctrl+R
675
        else if (chunk[0] === 19) restartServer();   // Ctrl+S
676
      }
677
    });
678
  }
679
  process.on('SIGINT', gracefulExit);
680
}
681

682
init();

在博客根目录保存为 dev.js（或者其他的名字也可以）

先安装依赖：

1
npm install chokidar express serve-static --save

1
pnpm add chokidar express serve-static

1
yarn add chokidar express serve-static

注意 Hexo 要全局安装。

然后直接运行命令：

1
node dev.js [端口] [选项]

选项有这几个：

选项	简写	含义
`--silent`	`-s`	静默模式，只输出脚本日志和 Hexo 的错误日志
`--quick`	`-q`	快速模式，跳过手动添加的延迟
`--direct`	`-d`	直接启动服务器，跳过首次构建（请确保静态文件已生成）
`--help`	`-h`	输出帮助

可以使用以下快捷键：

Ctrl + C：退出脚本
Ctrl + R：完整重构（hexo cl + hexo g）
Ctrl + S：重启本地服务器

脚本使用 chokidar 库，支持监测文件变动自动重新构建。以后改文章不用重新输入命令了！

另外，脚本自动构建使用的是 hexo g --incremental，对于文章变动比较高效。如果你改动了配置文件或主题文件，建议执行一次完整重建。

太方便了！当然，你也可以自己 Vibe Coding 一个，实现自己想要的功能！

说在最后#

本地预览的问题可算是解决了，这下可以安心写文章了。

以后打算再写一下关于 Hexo Solitude 的懒加载问题。随缘更新。

✨

写在前面#

大问题#

解决方案#

手敲命令#

万物皆可脚本#

说在最后#

评论区