Skip to content

工具栏集成

本文档介绍了如何将 Stagewise 工具栏集成到本 Hugo 网站中。

概述

Stagewise 工具栏已成功集成到本 Hugo 网站中，在开发期间通过浏览器工具栏提供 AI 编辑能力。

实现细节

1. 包安装

  • 包名：@stagewise/toolbar（v0.6.2）
  • 安装方式：通过 npm 作为开发依赖添加
  • 命令：npm install @stagewise/toolbar --save-dev

2. 集成方法

由于本项目采用 Hugo 静态网站生成器（非 React/Vue 等 JS 框架），因此直接使用了 @stagewise/toolbar 包，具体方法如下：

修改的文件

  1. assets/js/stagewise-toolbar.js - 初始化脚本
  2. layouts/partials/js-bundle.html - 集成到 Hugo 构建系统
  3. .vscode/extensions.json - VSCode 扩展推荐

主要特性

  • 仅开发环境加载：仅当 hugo.IsServer 为 true 时加载工具栏
  • 双重加载方式：
  • 与其他 JS 文件一起打包以保证兼容性
  • 直接模块加载以提升可靠性
  • 错误处理：加载失败时优雅降级

3. 开发模式检测

工具栏仅在开发模式下加载，利用 Hugo 的 hugo.IsServer 变量实现：

  • ✅ 仅在 hugo server 开发时显示
  • ✅ 不包含在生产构建中
  • ✅ 不影响生产性能

4. VSCode 扩展

在 .vscode/extensions.json 中添加了 stagewise.stagewise-vscode-extension 推荐扩展。

使用说明

开发者操作

  1. 启动开发服务器：
hugo server

  1. 打开浏览器，访问 http://localhost:1313

  2. 查看工具栏，位于网页右下角

  3. 如未显示工具栏：

  4. 检查浏览器控制台是否有错误信息
  5. 确认正在开发模式（hugo server）
  6. 验证 stagewise 包已安装：npm list @stagewise/toolbar

用户操作

如工具栏未显示，可通过 Discord 联系 stagewise 团队：https://discord.gg/gkdGsDYaKA

技术实现

JavaScript 加载策略

// 方法一：通过 Hugo 资源管道打包
{{ if hugo.IsServer }}
{{ $stagewiseToolbarJs := resources.Get "js/stagewise-toolbar.js" }}
{{ if $stagewiseToolbarJs }}
    {{ $jsBundleFiles = $jsBundleFiles | append $stagewiseToolbarJs }}
{{ end }}
{{ end }}

// 方法二：直接模块加载
{{ if hugo.IsServer }}
<script type="module">
  try {
    const { initToolbar } = await import('/node_modules/@stagewise/toolbar/dist/index.es.js');
    initToolbar({ plugins: [] });
    console.log('Stagewise toolbar initialized successfully');
  } catch (error) {
    console.warn('Failed to initialize stagewise toolbar:', error);
  }
</script>
{{ end }}

静态资源处理

为确保 Stagewise 工具栏在静态网站环境下正常工作，将工具栏文件从 node_modules/@stagewise/toolbar/dist/ 复制到 static/node_modules/@stagewise/toolbar/dist/，以便浏览器通过 HTTP 访问。

构建流程包含如下步骤：

mkdir -p static/node_modules/@stagewise/toolbar/dist/
cp node_modules/@stagewise/toolbar/dist/* static/node_modules/@stagewise/toolbar/dist/

这样可以确保： 1. 工具栏文件可通过 HTTP 访问 2. 工具栏仅在开发模式下工作 3. 生产构建无需任何更改（工具栏仅限开发环境）

开发模式检测

实现中包含多重检测以确保仅在开发环境加载：

  • Hugo 模板层：{{ if hugo.IsServer }}
  • JavaScript 层：主机名和端口检测
  • 错误处理：优雅降级

预期效果

集成后的 Stagewise 工具栏应满足：

  1. ✅ 仅在开发模式下显示
  2. ✅ 不包含在生产构建中
  3. ✅ 不产生任何 lint 错误
  4. ✅ 浏览器首次打开时只加载一次
  5. ✅ 仅在浏览器端执行，不影响 SSR 或服务器环境

故障排查

常见问题

  1. 工具栏未显示：确认已运行 hugo server 并检查浏览器控制台
  2. 模块加载错误：确认包已安装且可访问
  3. 构建错误：确保集成不影响生产构建

调试步骤

  1. 检查浏览器控制台初始化信息
  2. 验证包安装：npm list @stagewise/toolbar
  3. 确认开发服务器已启动：hugo server
  4. 检查网络面板模块加载情况

新建/修改的文件

新建文件

  • assets/js/stagewise-toolbar.js - Stagewise 初始化脚本
  • .vscode/extensions.json - VSCode 扩展推荐
  • STAGEWISE_INTEGRATION.md - 本集成文档

修改文件

  • layouts/partials/js-bundle.html - 增加 stagewise 加载逻辑
  • package.json - 添加 @stagewise/toolbar 依赖（npm 自动完成）

后续步骤

  1. 启动开发服务器：hugo server
  2. 在浏览器中打开网站
  3. 查看右下角的 stagewise 工具栏
  4. 如有问题，通过 Discord 联系 stagewise 团队

集成已成功完成！ 🎉