环境故障排除

本地测试失败但在 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 上有问题的文章。暂存服务器只会显示“糟糕”错误，但本地服务器应该显示用于调试的堆栈跟踪。

如果您看到类似于以下内容的错误，请确保在 frontmatter 中正确转义单引号。此外，请检查 redirect_from 块中的格式。有关更多信息，请参阅“使用 YAML frontmatter”。

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

本地调试

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

本文内容