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
如果您的版本过时,请按照您最初安装它的方式进行更新说明。
克隆此仓库及其子模块
如果您不是 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 并包含演示版本的链接。请考虑添加对您部署的提交的引用,以便审阅者知道是否有进一步的更改。