排查您的环境问题

排查本地失败但在 CI 中通过的测试

如果您在本地运行测试时在 tests/rendering/server.ts 中出现关于静态资源、样式表或客户端 JavaScript 包的失败，而相同的测试在 PR 的 CI 中通过，请运行命令 npm run build。这是一条一次性命令，可在本地生成静态资源。

欲了解更多信息，请参阅创建本地环境。

排查卡住的预发布部署

如果预发布部署等待时间超过十分钟，请尝试关闭您的拉取请求（不删除分支），然后重新打开。此操作会触发新的预发布部署，不会造成任何破坏。

如果仍未生效，请使用下面的命令通过在命令行中推送一个空提交来触发新的预发布部署。

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

排查卡住或停滞的 CI

如果您的测试在 “In progress” 或 “Pending” 状态下卡住超过一小时，请使用下面的命令通过在命令行中推送空提交来重新运行 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://:4000 上的有问题的文章。预发布服务器只会显示 “Oops” 错误，而本地服务器则会显示用于调试的堆栈跟踪信息。

如果看到类似以下的错误，请确保 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:
                 ^

检查内部链接

“Link Checker: On PR” 测试会报告站点上的失效链接，包括图片。如果存在失效链接，测试会失败，详情视图会显示 TitleFromAutotitleError 错误（仅报告失效链接的 URL），或显示更具描述性的报告，其中还列出包含失效链接的页面。

如果错误信息未包含失效链接的位置，您需要在 docs 仓库中搜索该失效链接以定位相应文件。

找到失效链接后，请确保链接已正确进行版本化。例如，若文章仅在 GHES 3.8+ 版本中存在，请确保链接也标记为 3.8+。

如果面向 GitHub Enterprise Server 的文章链接到不同版本的 GitHub Docs，请在路径中加入版本号，以防 URL 自动转换为包含 GitHub Enterprise Server 版本号的形式。下面的示例演示了如何从 GitHub Enterprise Server 文章链接到 Free、Pro 与 Team 版本的文章。

[{{ 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://:4000 上的任意页面，并在路径末尾添加 ?json=page，以显示一些底层信息，这些信息对调试可能有帮助。除了标题和简介等基础信息外，以下几个字段也可能有用。

字段	描述
`productVersions`	显示站点从 `productVersions` frontmatter 中解析出的内容。
`permalinks`	显示站点为该页面生成的所有永久链接。
`redirect_from`	显示 `redirect_from` frontmatter 中硬编码的重定向。
`redirects`	显示站点为该页面生成的所有重定向。
`includesPlatformSpecificContent`	显示站点是否检测到页面上存在平台特定内容。

使用 Liquid 处理

如果您的文本或代码示例中包含大括号 ({ 和 }) 之间的内容，需要使用 {% raw %} 与 {% raw %} 标签将其包裹，以在该段禁用 Liquid 处理。例如

使用

GITHUB_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}

避免

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

本文内容