环境故障排除

排查本地测试失败但在 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

排查本地服务器问题

如果您正在运行 `npm start` 并收到 `Cannot find module` 错误，请在重新启动服务器之前尝试以下命令。

npm install

如果这无法解决问题，请使用以下命令删除 `node_modules` 目录并重新安装。

rm -rf node_modules
npm install

排查暂存问题

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

npm start

服务器运行后，在浏览器中导航到 `https://127.0.0.1:4000` 上有问题的文章。暂存服务器只会显示“糟糕”错误，但本地服务器应显示用于调试的堆栈跟踪。

如果您看到类似以下错误，请确保在前面内容中正确转义单引号。此外，请检查 `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 Docs 的不同版本，请在路径中包含版本，以防止 URL 自动转换为包含 GitHub Enterprise Server 版本号。以下示例演示了如何从 GitHub Enterprise Server 文章链接到文章的免费版、专业版和团队版。

[{{ 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/)"

本地调试

在开发过程中，您可以访问 `https://127.0.0.1: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 }}$

本文内容