Docusaurus执行npm run deploy报错：需设置GIT_USER或指定USE_SSH

问题描述 #

我用Docusaurus 3.1.1、Node v20.10.0执行npm run deploy部署站点到GitHub Pages时，遇到以下错误：

或者直接弹出错误文本：

Error: Please set the GIT_USER environment variable, or explicitly specify USE_SSH instead!

完整错误日志如下：

[WARNING] 部署到GitHub Pages时，建议在站点配置中显式设置"trailingSlash"。
否则，GitHub Pages会在直接访问（而非导航时）为站点URL添加额外的尾部斜杠并进行服务器重定向。
该行为可能影响SEO并引发相对链接问题。

[INFO] 已调用部署命令...

Error: Please set the GIT_USER environment variable, or explicitly specify USE_SSH instead!
    at Command.deploy (F:\personal-sites\code-harbor-hub\node_modules\@docusaurus\core\lib\commands\deploy.js:70:19)

[INFO] Docusaurus版本: 3.1.1
Node版本: v20.10.0

我已经检查过环境变量，但没解决问题，求指导怎么修复这个错误、成功部署站点。

解决方案 #

方法1：临时设置GIT_USER环境变量再部署 #

根据你使用的终端类型，执行对应命令，把你的GitHub用户名替换成实际账号名：

• Windows CMD：

  set GIT_USER=你的GitHub用户名&& npm run deploy
  

• Windows PowerShell：

  $env:GIT_USER="你的GitHub用户名"; npm run deploy
  

• Linux/macOS 终端：

  GIT_USER=你的GitHub用户名 npm run deploy
  

方法2：用SSH方式部署（免GIT_USER） #

如果本地已经配置好GitHub的SSH密钥，直接设置USE_SSH=true就能跳过GIT_USER的要求，命令如下：

• Windows CMD：

  set USE_SSH=true&& npm run deploy
  

• Windows PowerShell：

  $env:USE_SSH="true"; npm run deploy
  

• Linux/macOS 终端：

  USE_SSH=true npm run deploy
  

额外处理：解决trailingSlash警告 #

为避免后续出现SEO问题或相对链接错误，建议在项目根目录的docusaurus.config.js里显式配置trailingSlash：

module.exports = {
  // ...其他已有的配置项
  trailingSlash: true, // GitHub Pages推荐设为true，也可根据需求设为false
};

内容的提问来源于stack exchange，提问作者Ajay Dhangar