Flutter 文档网站

Flutter 框架的文档网站，使用 Eleventy 构建并托管在 Firebase 上。

问题、错误和需求

我们欢迎对我们的网站提出贡献和反馈。请在我们的问题跟踪器中提交请求或创建拉取请求。对于简单的更改（如调整一些文本），使用 GitHub UI 进行更改最为简单。

如果您在 api.flutter.dev 上的 API 文档有问题，请在 flutter/flutter 仓库中提交这些问题，而不是在这个（flutter/website）仓库中。API 文档嵌入在 Flutter 的源代码中，因此由工程团队处理。

在提交 PR 之前

我们非常喜欢社区参与改进我们的文档！但在提交 PR 之前，请记住以下几点：

在分类问题时，我们有时会给问题贴上 PRs welcome 标签。但我们也欢迎针对其他问题的 PR - 不一定要有该标签。
请不要将我们的文档通过 Grammarly（或类似工具）运行，然后将这些更改作为 PR 提交。
我们遵循 Google 开发者文档风格指南 — 例如，不要使用"即"或"例如"，避免使用第一人称写作，避免使用将来时态。您可以从风格指南要点或词汇表开始，或使用每个风格指南页面顶部的搜索栏。

我们真诚感谢您愿意并乐于帮助保持网站文档的最新状态！

贡献

要更新此网站，请 fork 仓库，进行更改，然后生成拉取请求。对于小型、局部的更改（如样式和拼写错误修正），您可能不需要构建此网站。通常，您可以使用 GitHub UI 进行更改。如果需要，我们可以在您的拉取请求中自动部署更改。

[!重要]
如果您在本地克隆此仓库，请按照下面关于带子模块克隆的说明进行操作。

如果您的更改涉及代码示例、添加/删除页面或影响导航，请考虑在提交之前构建和测试您的工作。

如果您想要或需要构建网站，请按照以下步骤操作。

构建网站

对于超出简单文本和 CSS 调整的更改，我们建议在本地运行网站，以实现编辑-刷新循环。

获取先决条件

安装以下工具以构建和开发网站：

Flutter

需要 Flutter 的最新稳定版本（包括 Dart）来构建网站并运行其工具。如果您没有 Flutter 或需要更新，请按照安装 Flutter 或升级 Flutter 的说明进行操作。

如果您已经安装了 Flutter，请验证它是否在您的路径中，并且已经是最新的稳定版本：

flutter --version

Node.js

需要 Node.js 的最新稳定 LTS 版本来构建网站。如果您没有 Node.js 或需要更新，请从 Node.js 下载存档下载您计算机对应的版本并按照说明进行操作。如果您喜欢，可以使用版本管理器，如 nvm，并在仓库的根目录运行 nvm install。

如果您已经安装了 Node，请验证它是否在您的路径中，并且已经是最新的稳定版本 （当前为 20.12 或更高版本）：

node --version

如果您的版本过时，请按照您最初安装它的方式进行更新说明。

克隆此仓库及其子模块

[!注意] 此仓库有 git 子模块，这会影响您克隆它的方式。GitHub 文档有关于分叉和克隆仓库的一般帮助。

如果您不是 Flutter 组织的成员，我们建议您在自己的账户下创建此仓库的分叉，然后从该分叉提交 PR。

一旦您有了分叉（或者您是 Flutter 组织成员），_选择以下一种_子模块克隆技术：

使用 --recurse-submodules 选项同时克隆仓库及其子模块：

git clone --recurse-submodules https://github.com/flutter/website.git

如果您已经克隆了仓库但没有其子模块，则从仓库的根目录运行此命令：
```
git submodule update --init --recursive
```

[!注意] 在开发过程中的任何时候，您都可以使用 git submodule 命令刷新子模块：
git pull && git submodule update --init --recursive

设置本地环境并提供更改

在继续设置网站基础设施之前，请按照获取先决条件中的说明验证是否已设置并可用正确版本的 Flutter 和 Node.js。

可选： 克隆仓库及其子模块后，为您的更改创建一个分支：
```
git checkout -b <分支名称>
```
从仓库的根目录获取网站的 Dart 依赖项。
```
dart pub get
```
（可选 - 我们强烈建议您使用 pnpm，但您也可以使用 npm。）安装 pnpm，这是一个替代的、高效的 npm 包管理器。如果您已经有 pnpm，请验证您是否拥有最新的稳定版本。
```
node --version
```
如果您还没有安装 pnpm，我们建议使用 corepack 来安装和管理 pnpm 版本，因为 corepack 与大多数 Node 安装捆绑在一起。如果您使用 Homebrew 安装了 node，则需要单独安装 corepack：
```
brew install corepack
```
如果您以前没有使用过 corepack，首先需要使用 corepack enable 启用它。然后，要安装正确的 pnpm 版本，从仓库的根目录运行 corepack install：
```
corepack enable;
corepack install
```

要安装 pnpm 而不使用 corepack，您可以使用您喜欢的安装方法。

（可选）一旦您安装并设置好 pnpm，使用 pnpm install 获取网站的 npm 依赖项。我们强烈建议您使用 pnpm，但您也可以使用 npm。
```
pnpm install
```
每当您合并最新的 main 分支更改，或在构建网站时遇到依赖或导入错误，请重新运行 pnpm install。
在根目录下，运行 dash_site 工具以验证您的设置并了解可用的命令。
```
./dash_site --help
```
在根目录下，在本地服务器上运行网站。
```
./dash_site serve
```
此命令会生成网站并在终端中打印的本地端口上提供服务。
通过导航到 http://localhost:4000 在浏览器中查看您的更改。

注意，如果端口 4000 被占用，端口可能会不同。

如果您想查看原始生成的 HTML 输出和结构，可以在文件资源管理器或 IDE 中查看 _site 目录。
对本地仓库进行更改。

大多数更改后，网站应该会自动重新构建，但如果有些内容没有更新，请退出进程并重新运行命令。我们计划改进此功能。如果发生这种情况，请开启一个新的 issue 来跟踪问题。
将您的更改提交到分支并提交您的 PR。

如果您的更改较大，或者您想测试它，请考虑验证您的更改。

[!提示] 要查找可以运行的其他命令，请在仓库的根目录下运行 ./dash_site --help。

验证您的更改

检查文档和示例代码

如果您对 /examples 或 /tool 目录中的代码进行了更改，请提交您的工作，然后运行以下命令以验证它是最新的并符合网站标准。

./dash_site check-all

如果此脚本报告任何错误或警告，请解决这些问题并重新运行命令。如果您遇到任何问题，请在您的 issue 或 pull request 上留言，我们会尽力帮助您。您也可以在 Flutter 贡献者 Discord 上的 #hackers-devrel 频道与我们聊天！

刷新代码摘录

如果构建失败并显示错误 Error: Some code excerpts needed to be updated!，这意味着网站 Markdown 文件中的一个或多个代码摘录与相应 .dart 文件中声明的代码区域不一致。

.dart 文件是代码片段的真实来源，而 Markdown 文件中前面的 <?code-excerpt> 指令指定了如何从 .dart 文件复制片段。

要解决此错误并更新 Markdown 片段以匹配，请在 website 目录的根目录下运行 ./dash_site refresh-excerpts。

要了解更多关于创建、编辑和使用代码摘录的信息，请查看摘录更新器包文档。

[可选] 部署到演示站点

提交的 pull request 可以由网站维护者自动部署到演示站点。但如果您想自己部署网站，可以构建完整版本并将其上传到 Firebase。

如果您还没有 Firebase 项目，

导航到 Firebase 控制台并创建您自己的 Firebase 项目（例如，flutter-dev-staging）。
返回到本地终端并验证您是否已登录。
```
firebase login
```

确保您的项目存在并激活该项目：

firebase projects:list
firebase use <your-project>

在仓库的根目录下，构建网站：
```
./dash_site build
```
这将构建网站并将其复制到您本地的 _site 目录。如果该目录之前存在，它将被替换。
部署到您激活的 Firebase 项目的默认托管站点：
```
firebase deploy --only hosting
```
导航到 GitHub 上的 PR 并包含演示版本的链接。请考虑添加对您部署的提交的引用，以便审阅者知道是否有进一步的更改。