Skip to main content

问题与分析

目录​

问题一：Docusaurus 分类链接 URL 规则​

问题描述​

在 docusaurus.config.js 中配置 footer 链接时，指向文档分类的链接报错 "broken links"。

错误示例：

[ERROR] Docusaurus found broken links!
Frequent broken links are linking to:
- /docs/category/ee
- /docs/category/001-ee

根本原因​

Docusaurus 生成的分类 URL 是基于 _category_.json 中的 label 字段，而不是文件夹名称。

规则说明​

文件夹路径_category_.json 中的 label生成的分类 URL
docs/001_ee/"Power Electronics"/docs/category/power-electronics
docs/002_ai/"AIGC"/docs/category/aigc
docs/998_tools/"Tools"/docs/category/tools

转换规则：

  1. 读取 _category_.json 中的 label 值
  2. 转换为小写
  3. 空格替换为连字符 -
  4. 最终生成 /docs/category/<转换后的label>

正确配置方式​

在 docusaurus.config.js 中：

footer: {
  links: [
    {
      title: 'Docs',
      items: [
        {
          label: '文档',
          to: '/docs/category/power-electronics',  // 基于 label: "Power Electronics"
        },
      ],
    },
  ],
},

如何确认正确的分类 URL​

方法一：查看 _category_.json

cat docs/001_ee/_category_.json

输出：

{
  "label": "Power Electronics",  // → /docs/category/power-electronics
  "position": 1,
  "link": {
    "type": "generated-index"
  }
}

方法二：构建后查看输出目录

npm run build
ls build/docs/category/

输出：

aigc/
claude-code/
control/
devices/
power-electronics/  ← 这是实际的 URL 路径
tools/

修改分类名称时的注意事项​

  1. 修改文件夹名 → 不影响分类 URL
  2. 修改 _category_.json 中的 label → 会改变分类 URL，需要同步更新所有引用

相关文件​

  • docusaurus.config.js - 配置导航和页脚链接
  • docs/*/_category_.json - 定义分类显示名称和 URL slug

问题二：Git 提交与部署流程​

问题描述​

运行 npm run build 和 npm run deploy 后，源代码没有推送到 GitHub。

命令说明​

命令作用分支
git add .添加修改到暂存区-
git commit -m "描述"提交修改-
git push推送源代码→ master
npm run build构建静态文件-
npm run deploy部署到 GitHub Pages→ gh-pages

重要区别​

  • npm run build 和 npm run deploy 不会把源代码推送到 Git
  • 源代码在 master 分支，需要单独 git push
  • 部署后的网站在 gh-pages 分支

完整部署流程​

# 1. 提交源代码到 master
git add .
git commit -m "更新内容描述"
git push

# 2. 构建并部署到 gh-pages
npm run build
npm run deploy

一键命令​

git add . && git commit -m "更新" && git push && npm run build && npm run deploy

.gitignore 自动过滤​

git add . 会自动跳过 .gitignore 中配置的文件：

被忽略的文件/目录说明
/node_modules依赖包（不提交）
/build构建输出（部署时生成）
.docusaurus缓存文件
.cache-loader缓存文件
.DS_StoremacOS 系统文件
.env.*环境变量文件
*.log日志文件
.vscodeVS Code 配置
*.bat批处理脚本

预览将要提交的文件​

git status              # 查看修改状态
git add . --dry-run     # 预览将要添加的文件（不实际执行）

问题三：MDX 语法错误​

问题描述​

Docusaurus 构建时报错：

Error: MDX compilation failed
Cause: Unexpected character `/` (U+002F) before local name

根本原因​

在 .md 文件中使用了 <https://example.com> 格式的链接。

Docusaurus 使用 MDX 解析器，<...> 会被解析为 JSX 组件，导致错误。

错误示例​

推荐使用 npm 安装，其他安装方式：<https://example.com>

正确写法​

推荐使用 npm 安装，其他安装方式：[示例网站](https://example.com)

修复方法​

将所有 <URL> 格式的链接改为 [文字](URL) 格式：

错误写法正确写法
<https://example.com>[https://example.com](https://example.com)
<https://nodejs.org>[Node.js 官网](https://nodejs.org)

问题四：Windows PowerShell 执行策略限制​

问题描述​

在 Windows PowerShell 中运行 claude 命令时出现以下错误：

无法加载文件 C:\Users\Wald\AppData\Roaming\npm\claude.ps1，因为在此系统上禁止运行脚本。
有关详细信息，请参阅 https:/go.microsoft.com/fwlink/?LinkID=135170 中的 about_Execution_Policies。
所在位置 行:1 字符: 1
+ claude
+ ~~~~~~
    + CategoryInfo          : SecurityError: (:) []，PSSecurityException
    + FullyQualifiedErrorId : UnauthorizedAccess

根本原因​

Windows PowerShell 默认启用安全策略，禁止运行未签名的脚本文件。npm 安装的 claude.ps1 是一个未签名的 PowerShell 脚本，因此被系统拦截。

执行策略说明​

执行策略（Execution Policy）是 PowerShell 的安全特性，用于控制脚本的运行权限：

策略说明
Restricted默认策略，不允许运行任何脚本
RemoteSigned本地脚本可运行，远程脚本必须签名
Unrestricted允许运行所有脚本（有安全风险）
Bypass临时绕过所有限制

解决方案​

方案一：修改当前用户的执行策略（推荐）

在 PowerShell 以管理员身份运行，执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

优点：

  • 一次设置永久生效
  • RemoteSigned 是较安全的策略，只允许本地脚本运行
  • 不影响系统其他用户

方案二：临时绕过（不推荐长期使用）

powershell -ExecutionPolicy Bypass -File "C:\Users\Wald\AppData\Roaming\npm\claude.ps1"

缺点：每次都需要输入完整命令

验证是否生效​

Get-ExecutionPolicy -List

输出示例：

        Scope ExecutionPolicy
        ----- ---------------
MachinePolicy       Undefined
   UserPolicy       Undefined
      Process       Undefined
  CurrentUser    RemoteSigned  ← 应该显示这个
 LocalMachine       Undefined

总结​

项目内容
问题PowerShell 禁止运行未签名脚本
原因默认执行策略限制
解决Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
安全性RemoteSigned 是推荐的安全策略

问题五：GitHub Pages trailingSlash 配置​

问题描述​

Docusaurus 构建时出现警告：

[WARNING] When deploying to GitHub Pages, it is better to use an explicit "trailingSlash" site config.
Otherwise, GitHub Pages will add an extra trailing slash to your site urls only on direct-access (not when navigation) with a server redirect.
This behavior can have SEO impacts and create relative link issues.

根本原因​

GitHub Pages 有一个特殊行为：

  • 用户直接访问 /docs/intro 时，服务器会重定向到 /docs/intro/（添加末尾斜杠）
  • 但网站内部导航链接可能是 /docs/intro（无斜杠）
  • 这会导致同一个页面有两个不同的 URL，影响 SEO 和相对链接解析

trailingSlash 配置说明​

配置值URL 格式效果
trailingSlash: false/docs/introURL 不带末尾斜杠
trailingSlash: true/docs/intro/URL 带末尾斜杠

解决方案​

在 docusaurus.config.js 中添加 trailingSlash 配置：

const config = {
  // ... 其他配置

  organizationName: 'beanspower',
  projectName: 'beanspower.github.io',

  trailingSlash: false,  // 添加此配置

  // ... 其他配置
};

推荐设置​

对于 GitHub Pages，推荐设置 trailingSlash: false：

  1. 现代 Web 更倾向于无斜杠的 URL
  2. 链接更简洁美观
  3. Docusaurus 默认生成的链接就是无斜杠的
  4. 避免重定向导致的 SEO 问题

记录时间: 2026-03-10