Skip to main content

对环境进行故障排除

了解如何解决本地环境和 GitHub Docs 暂存平台的问题。

“参与 GitHub Docs”部分中的文章指的是文档本身,是 GitHub 员工和开放源代码参与者的资源。

对在本地失败但在 CI 中通过的测试进行故障排除

如果你在本地运行测试,并在 tests/rendering/server.js 中遭遇有关静态资产、样式表或客户端 JavaScript 捆绑包的失败,但在 PR 上的 CI 中通过了相同的测试,请运行命令 npm run build。 这是一个一次性命令,用于在本地创建静态资源。

有关详细信息,请参阅“创建本地环境”。

对停滞的暂存部署进行故障排除

如果暂存部署挂起超过十分钟,请尝试关闭拉取请求(无需删除分支),然后重新打开它。 这样做会触发新的暂存部署。 它不会破坏任何东西。

如果这不起作用,请使用下面的命令,通过在命令行上推送一个空提交来触发新的暂存部署。

git commit --allow-empty -m 'empty commit to redeploy staging'
git push

对停滞或卡住的 CI 进行故障排除

如果测试卡在“正在进行”或“挂起”状态超过一个小时,请使用下面的命令,通过在命令行上推送一个空提交来重新运行 CI。

git commit --allow-empty -m 'empty commit to rerun CI'
git push

对本地服务器问题进行故障排除

如果正在运行 script/server 并收到 Cannot find module 错误,请在重启服务器之前尝试以下命令。

npm install

如果这样做不能解决问题,请使用以下命令删除 node_modules 目录并重新安装。

rm -rf node_modules
npm install

对暂存问题进行故障排除

如果遇到暂存服务器问题,并在本地运行站点,则应在浏览器中或命令行上看到有关错误的更多信息。 请在本地查看分支,并使用以下命令启动本地服务器。

script/server

当服务器正在运行时,请在浏览器中导航到 https://localhost:4000 上有问题的文章。 暂存服务器只会显示“Oops”错误,但本地服务器应显示用于调试的堆栈跟踪。

如果看到类似下面的错误,请确保在前面的内容中正确转义了单引号。 此外,请检查 redirect_from 块中的格式设置。 有关详细信息,请参阅“使用 YAML 前辅文”。

error parsing file: /Users/z/git/github/docs/content/dotcom/articles/troubleshooting-custom-domains-and-github-pages.md
(node:89324) UnhandledPromiseRejectionWarning: YAMLException: can not read a block mapping entry; a multiline key may not be an implicit key at line 4, column 14:
    redirect_from:
                 ^

“链接检查器:在 PR 上”测试报告网站上断开的链接,包括图像。 如果存在断开的链接,则测试将失败,测试的详细信息视图将显示 TitleFromAutotitleError 错误(仅报告断开的链接 URL)或更具描述性的报告,其中还列出了包含断开的链接的页面。

如果错误不包括断开的链接的具体位置,则需要在 docs 存储库中搜索断开的链接以查找文件。

找到断开的链接时,请确保链接的版本正确。 例如,如果文章仅适用于 GHES 版本 3.8+,请确保链接的版本适用于 3.8+。

如果可用于 GitHub Enterprise Server 的文章链接到仅 GitHub.com 的文章,请在路径中包含版本,以防止 URL 自动转换为包含 GitHub Enterprise Server 版本号。 以下示例演示如何从 GitHub Enterprise Server 文章链接到仅 GitHub.com 的文章。

[{{ data variables.product.prodname_github_connect }} Addendum to the {{ data variables.product.prodname_enterprise }} License Agreement](/free-pro-team@latest/articles/github-connect-addendum-to-the-github-enterprise-license-agreement/)"

在本地进行调试

在开发过程中,你可以访问 http://localhost:4000 上的任何页面,并在路径末尾添加 ?json=page,以显示一些可能对调试有帮助的基础信息。 除了标题和简介等基本信息外,这些字段可能很有用。

字段说明
productVersions显示站点正在从 productVersions 前辅文分析的内容。
permalinks显示网站为页面生成的所有永久链接。
redirect_from显示 redirect_from 前辅文中的硬编码重定向。
redirects显示站点为页面生成的所有重定向。
includesPlatformSpecificContent显示站点是否在页面上检测到任何特定于平台的内容。

使用 Liquid 处理

如果文本或代码示例包含大括号({})之间的内容,则需要将其包装到 &#123% raw %}&#123% raw %} 标记之间,以禁用该部分的 Liquid 处理。 例如:

  • 使用:

    GITHUB_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}
    
  • 避免:

    GITHUB_TOKEN: $${{ secrets.GITHUB_TOKEN }}$