对环境进行故障排除

本文内容

了解如何解决本地环境和 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 }}$