前端开发#

Home Assistant 前端使用 Web Components 构建。关于我们技术选型的更多背景，请参阅这篇博客文章。

#设置环境

请先按照我们的devcontainer development environment指南设置合适的开发环境。

#获取代码

第一步是 fork frontend repository，并添加 upstream remote。你可以将 fork 后的仓库放在系统中的任意位置。

git clone git@github.com:YOUR_GIT_USERNAME/frontend.git
cd frontend
git remote add upstream https://github.com/home-assistant/frontend.git

#配置 Home Assistant

你需要先准备一个 Home Assistant 实例。关于开发实例，请参阅我们的设置开发环境指南。

有两种方式可以测试前端。你可以运行一个 Home Assistant Core 开发实例，或者将前端配置为连接到一个现有的 Home Assistant 实例。第一种方式与生产环境中的工作方式一致。第二种方式允许以前端开发模式连接现有 Home Assistant，并尽量减少干扰。缺点是并非所有内容都能以这种方式测试。例如，登录页面始终会使用你的 Home Assistant 内置的那个版本。

import Tabs from '@theme/Tabs' import TabItem from '@theme/TabItem'

"mounts": [
  "source=/path/to/hass/frontend,target=/workspaces/frontend,type=bind,consistency=cached"
]

frontend:
  development_repo: /workspaces/frontend

frontend:
  # Example path: /home/paulus/dev/hass/frontend
  development_repo: /path/to/hass/frontend

http:
  cors_allowed_origins:
    - http://localhost:8124

script/develop_and_serve

script/develop_and_serve -c https://homeassistant.local:8123

script/develop_and_serve -p 8654

#安装 Node.js（仅手动环境）

构建前端需要 Node.js。安装 node.js 的首选方式是使用 nvm。请按照 README 中的说明安装 nvm，然后运行以下命令安装正确版本的 node.js：

nvm install

Yarn 用作 node modules 的包管理器。按这里的说明安装 yarn。

#安装开发依赖并获取最新翻译

通过安装开发依赖并下载最新翻译来初始化前端开发环境。

nvm use
script/bootstrap
script/setup_translations

:::note 即使你使用的是 dev containers，这一步也需要手动完成。另外，系统会要求你输入一个代码并授权脚本获取最新翻译。

如果之前的授权不再可用（例如在获取翻译时看到 “Bad Credentials” 错误），请删除 translations 文件夹中的 token.json 文件，然后再次执行 script/setup_translations 以重新触发授权流程。

#开发

#运行开发服务器

运行以下脚本以构建前端并启动开发服务器：

nvm use
script/develop

当脚本完成前端构建，并且 Home Assistant Core 已正确配置后，可通过 http://localhost:8123 访问前端。服务器会在你修改源文件时自动重新构建前端。

#在现有 HA 实例上运行开发前端

运行以下命令启动开发服务器：

nvm use
script/develop_and_serve -c https://homeassistant.local:8123

你可能需要将 "https://homeassistant.local:8123" 替换为你的本地 Home Assistant url。

#浏览器设置

打开 Google Chrome 的 Developer tools，并确保已禁用缓存且相关设置正确，以避免使用陈旧内容：

1. 在 Network > Disable cache 中勾选禁用缓存

2. 在 Application > Service Workers > Bypass for network 中启用 Bypass for network

#创建 pull requests

如果你计划向 Home Assistant 代码库提交 PR，你需要 fork frontend 项目，并将你的 fork 添加为 Home Assistant frontend 仓库的一个 remote。

git remote add fork <github URL to your fork>

当你完成更改并准备推送时，切换到 frontend 项目的工作目录，然后推送你的更改

git add -A
git commit -m "Added new feature X"
git push -u fork HEAD

#构建前端

如果你更改了前端打包方式，可能有必要在主仓库中测试一个新的已打包前端版本（而不是直接指向 frontend 仓库）。为此，请先运行 script/build_frontend 构建前端的生产版本。

要在 Home Assistant 中测试它，请从主 Home Assistant 仓库运行以下命令：

pip3 install -e /path/to/hass/frontend/ --config-settings editable_mode=compat
hass --skip-pip-packages home-assistant-frontend

#测试现有 PR

有时你需要在不同环境中测试前端更改，或在不搭建完整开发环境的情况下进行测试。例如，你可能想在 Home Assistant OS 实例上测试更改，或在 PR 合并前验证某个修复是否在你的特定环境中生效。

development_pr 选项允许你通过自动下载并使用来自 GitHub 的前端 artifact，轻松测试前端 PR。

#配置

要使用此功能，你需要同时提供一个 PR 编号和一个 GitHub token。

#创建 GitHub token

1. 前往 GitHub Settings > Developer Settings > Personal Access Tokens > Fine-grained tokens
2. 点击 "Generate new token"
3. 为它指定一个具有描述性的名称，例如 "Home Assistant Frontend Testing"
4. 设置过期日期（推荐：90 天或更短）
5. 在 "Repository access" 下选择 "Public Repositories (read-only)"
6. 跳过 'Permissions' 部分（留空）
7. 点击 "Generate token"
8. 立即复制 token（之后将无法再次查看）

#在 Home Assistant 中配置

将以下内容添加到你的 configuration.yaml：

frontend:
  development_pr: <PR_NUMBER>
  github_token: <YOUR_GITHUB_TOKEN>

例如，要测试 PR #12345：

frontend:
  development_pr: 12345
  github_token: ghp_your_token_here

添加该配置后，重启 Home Assistant 以使更改生效。

#恢复到生产前端

若要停止使用 PR 构建并恢复为标准 Home Assistant 前端：

1. 从你的 configuration.yaml 中移除 development_pr 和 github_token 两行
2. 重启 Home Assistant

Home Assistant 会自动恢复使用内置的生产前端。

#工作原理

当你配置了 development_pr 后，Home Assistant 会在启动期间从 GitHub 上指定的 PR 下载前端构建 artifact，并使用它替代生产版本。该 artifact 会缓存在本地；在后续重启时，Home Assistant 会通过比较 SHA 值来检查该 PR 是否有新提交。如果发现了更新版本，它会自动下载更新后的 artifact。

#使用场景

这在以下情况下尤其有用：

• 在 HAOS 上测试：无需搭建开发环境，即可在 Home Assistant OS 上测试 PR
• 特定环境测试：验证某个修复是否在你的特定硬件、网络或浏览器配置上有效
• 快速验证：无需克隆仓库并在本地构建前端，也能测试修复或功能

#限制

• PR 必须成功构建，并且 GitHub 上有可用的 artifacts
• 前端 artifacts 仅在 PR 构建完成后的 7 天内可用
• 此功能仅用于测试，不应在生产环境中使用

#重新生成 artifact

如果 artifact 已不可用（例如已超过 7 天），或者你想在该 PR 中测试新的上游更改，这会很有帮助。

如果你是该 PR 的作者，可以通过以下方式触发新的 artifact：

• 更新你的分支——可以将 dev 分支合并进来，或 rebase 到最新的 dev 分支之上。这会触发构建流水线，并生成一个可供 Home Assistant 下载的新 artifact。
• 关闭并重新打开该 PR，以触发新的构建。

如果你不是作者，可以请对方更新其 PR 分支以触发新的构建。