问题场景 #

基于React + Next.js 15.1.2的项目，执行npm run deploy（实际对应命令gh-pages -d out）时触发权限错误，完整报错日志如下：

> project@0.1.0 predeploy
> npm run build


> project@0.1.0 build
> next build

   ▲ Next.js 15.1.2

   Creating an optimized production build ...
 ✓ Compiled successfully
 ✓ Linting and checking validity of types
 ✓ Collecting page data
 ✓ Generating static pages (4/4)
 ✓ Collecting build traces
 ✓ Exporting (3/3)
 ✓ Finalizing page optimization

Route (app)                              Size     First Load JS
┌ ○ /                                    206 kB          312 kB
└ ○ /_not-found                          979 B           107 kB
+ First Load JS shared by all            106 kB
  ├ chunks/4bd1b696-1d398b649b281e55.js  52.9 kB
  ├ chunks/517-056b7465b3216e08.js       50.6 kB
  └ other shared chunks (total)          1.99 kB


○  (Static)  prerendered as static content


> project@0.1.0 deploy
> gh-pages -d out

ProcessError: warning: failed to remove _next/static/8FM1BF8OK1Exh6Ewqsqjb/: Permission denied

    at ChildProcess.<anonymous> (C:\Users\realhuman\OneDrive\Documents\GitHub\project\node_modules\gh-pages\lib\git.js:42:16)
    at ChildProcess.emit (node:events:524:28)
    at maybeClose (node:internal/child_process:1101:16)
    at ChildProcess._handle.onexit (node:internal/child_process:304:5)

该命令此前可正常执行，当前持续报错；npm run dev可正常运行无异常。

运行环境：Windows 11、Powershell 7.4.6、npm 10.9.0、Node.js v22.12.0，已拥有目标GitHub仓库完整所有权，未修改仓库内容。

已尝试的无效方案 #

• 删除预生成的.next/和out/文件夹
• 重启电脑
• 以管理员身份运行Powershell
• 通过nvm重新安装npm和Node.js
• 重新安装Node模块（rm -rf node_modules && npm install）

遗漏排查点与解决方法 #

1. 解除OneDrive文件锁定 #

项目存储在OneDrive目录下，OneDrive的实时同步可能锁定out/或gh-pages临时文件。

• 解决：暂停OneDrive同步后再执行npm run deploy；或把项目迁移到非OneDrive本地目录。

2. 清理进程占用 #

Windows系统中，浏览器预览窗口、杀毒软件、文件管理器等进程可能占用out/_next/static/下的文件。

• 解决：用任务管理器关闭所有可能访问项目文件的进程；或通过资源监视器搜索8FM1BF8OK1Exh6Ewqsqjb相关进程并强制结束。

3. 修复gh-pages缓存目录权限 #

gh-pages会在项目根目录生成.gh-pages/临时缓存文件夹，可能存在权限异常。

• 解决：手动删除.gh-pages/文件夹后重新执行部署命令；或给该目录添加当前用户的完全控制权限。

4. 禁用gh-pages的自动清理 #

默认gh-pages会清理目标分支旧文件，可能触发权限冲突，尝试跳过清理：

• 解决：修改package.json中的deploy命令为：

  "deploy": "gh-pages -d out --no-clean"
  

  部署成功后，可手动清理GitHub Pages分支的旧文件，再尝试恢复clean选项。

5. 手动执行git部署绕开gh-pages工具 #

直接通过git命令完成部署，避免gh-pages模块的权限问题：

1. 执行npm run build生成out/文件夹
2. 创建临时分支temp-deploy，将out/下所有文件移动到项目根目录（注意不要覆盖源码）
3. 提交所有文件到temp-deploy分支
4. 强制推送到GitHub的gh-pages分支：git push origin temp-deploy:gh-pages -f
5. 删除临时分支，恢复项目原有结构

6. 排查杀毒软件拦截 #

Windows Defender或第三方杀毒软件可能误将gh-pages的文件删除操作判定为恶意行为，从而拦截。

• 解决：暂时关闭杀毒软件后执行部署命令；或把项目目录添加到杀毒软件的信任列表。

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