Safari 中安装 Angular DevTools：实验性 Web 扩展的构建与启用完整指南

Safari 中安装 Angular DevTools实验性 Web 扩展的构建与启用完整指南【免费下载链接】angularDeliver web apps with confidence 项目地址: https://gitcode.com/GitHub_Trending/an/angularAngular DevTools 在 Safari 中的支持目前处于实验阶段官方不直接分发 Safari 版扩展包而是要求开发者在 macOS Xcode 环境下自行将 Chrome 版构建产物转换为 Safari Web Extension。本文以 devtools/docs/safari.md 为主干结合仓库中真实的 Bazel 构建脚本与扩展清单源码给出从环境准备、构建、转换、签名到验证的端到端可复现流程帮助你最终在 Safari 的 Web Inspector 中看到并启用 Angular 专用面板。一、先了解背景Angular DevTools 在 Safari 上的形态Angular DevTools 是一个面向浏览器 DevTools 的扩展用于调试与剖析 Angular 应用。它本质上是一个同时面向 Chrome 与 Firefox 打包的浏览器扩展在 devtools/package.json 的说明中可以确认仓库通过一套 Bazel 目标产出统一的前端面板ng-devtools与浏览器壳层shell-browser再依据浏览器标志flag挑选对应的manifest.json。Safari 从 macOS 13Ventura起将「Web 扩展」统一到 Xcode 的safari-web-extension-converter工具链上。Angular DevTools 仓库正是借助这条官方转换链路把一份「以 Chrome 配置构建的 Manifest V3 扩展」转换成可在 Safari 中运行的扩展工程。因此整个流程中并不存在 Safari 专属的源码分支——你的构建入口仍是面向 Chrome 的pnpm devtools:build:chromeSafari 只是它被二次消费的目标运行时。这一点也从文档标题中的 (experimental) 得到印证该流程属于实验性支持未作为官方发布渠道遇到问题时需要自行结合源码排查。二、前置条件原文档给出的硬性条件是Xcode 13。结合仓库实际构建链路完整的前置条件还包括条件说明依据macOSsafari-web-extension-converter为 macOS / Xcode 专属工具devtools/docs/safari.mdXcode 13用于打开转换后生成的 Xcode 工程并编译扩展devtools/docs/safari.mdNode.js pnpm仓库级依赖管理建议按 .nvmrc 安装对应 Node 版本后再pnpm install --frozen-lockfiledevtools/README.mdbazelisk实际执行构建仓库内所有devtools:build:*脚本都由 bazelisk 驱动package.json需要特别注意所有 pnpm 命令都必须回到仓库根目录执行即本文所在仓库的根目录而不是devtools/子目录下文档中dist/bin/...的产物路径同样以仓库根目录为基准。构建目前只保证在 Debian Linux、macOS 以及通过 WSL 的 Windows 上成功未配置过原生 Windows 构建。三、逐步安装流程下面将 devtools/docs/safari.md 的五个步骤逐一展开并补充源码层面的验证与常见坑点。步骤 1打开 Safari 的「开发」菜单打开 Safari勾选Safari - 偏好设置 - 高级 - 在菜单栏中显示“开发”菜单。这是后续所有实验性开关与扩展管理入口的前提。步骤 2启用 Web Inspector 扩展实验特性在菜单栏依次进入开发 - 实验性功能 - Web Inspector Extensions确保该选项处于勾选状态。这是 Safari 加载浏览器 DevTools 类扩展的总开关。Angular DevTools 的形态与 Chrome 中的 DevTools 面板一致它不是普通工具栏按钮而是注册到 Web InspectorSafari 版开发者工具中的一个新面板。该开关未打开时即便后续完成了 Xcode 构建扩展也无法注入到 Web Inspector 中。步骤 3以 Chrome 配置构建扩展在仓库根目录执行pnpm devtools:build:chrome该命令对应的真实 Bazel 指令定义在根目录 package.json 中bazelisk build --//devtools/projects/shell-browser/src:flag_browserchrome //devtools/projects/shell-browser/src:prodapp要点如下它通过 Bazel 的string_flag机制把浏览器标志设置为chrome。该标志在 devtools/projects/shell-browser/src/BUILD.bazel 中声明可选值为chrome/firefox默认即为chrome。构建完成后产物输出在dist/bin/devtools/projects/shell-browser/src/prodapp——这是一个完整的、可直接加载的「未打包扩展」目录。该目录由 Bazel 的extension_package目标prodapp组装而成。从 devtools/projects/shell-browser/src/BUILD.bazel 可以清楚看到它聚合了哪些内容bundle用 esbuild 打包的ng-devtools面板主体入口为main.ts目标 ES2022devtools_bundle注册 DevTools 面板的脚本入口为 devtools.tscopy_manifest根据浏览器标志从 manifest.chrome.json 或 manifest.firefox.json 复制生成manifest.json一组在页面与后台运行的 bundlebackend_bundle、background_bundle、content_script_bundle、detect_angular_bundle、ng_validate_bundle、devtools_connected_flag_bundle静态资源、样式与 popup 页面。我们为 Safari 转换的就是这份 Chrome 产物无需重新构建 Safari 专用包。步骤 4用 Xcode 的转换器生成 Safari 扩展工程执行xcrun safari-web-extension-converter --macos-only dist/bin/devtools/projects/shell-browser/src/prodapp说明xcrun会调用随 Xcode 附带的safari-web-extension-converter工具--macos-only表示只为 macOS而非 iOS/iPadOS生成 Safari 应用扩展工程。该命令会把上面的未打包 Chrome 扩展转换成一个可编译的 Xcode 工程。由于prodapp中已经是完整的manifest.json 各 JS bundle 图标 popup 页面转换器无需额外下载或改造资源。命令结束后通常会自动打开 Xcode并载入刚生成的工程。步骤 5在 Xcode 中构建并启用扩展在 Xcode 中点击 Build构建按钮等待扩展编译完成。构建完成后macOS 会弹出系统提示询问是否打开 Safari 并启用该扩展确认即可。如何确认启用成功Safari 工具栏会出现Angular 图标若未自动出现可前往Safari - 偏好设置 - 扩展或在 Safari 设置中的扩展标签页手动勾选启用该扩展。从仓库源码看扩展的「Angular 图标」由 assets 目录下的多尺寸 PNG 提供16/48/128并且 Angular DevTools 通过页面检测脚本根据当前页面是否为 Angular 应用来切换彩色/灰度图标与 popup 内容——这就是为什么你在非 Angular 页面上看到的是灰色图标。步骤 6验证功能打开任意一个**开发模式dev mode**下运行的 Angular 应用然后打开 Safari 的 Web Inspector开发菜单 - 显示网页检查器此时检查器顶部应出现Angular标签页。⚠️ 为什么必须是开发模式这与仓库的页面检测机制直接相关扩展通过 detect-angular.ts 注入检测脚本读取页面上 Angular 暴露的调试全局对象ng-devtools-backend依赖的应用调试 API。生产构建默认关闭了这些调试钩子因此生产版应用无法被识别。如果看到「Angular application not detected」或缺少 Angular 标签请优先确认被测应用以开发模式运行并按步骤 2 确认「Web Inspector Extensions」实验特性已勾选。四、深入理解被转换的究竟是怎样一份扩展转换器喂给 Xcode 的prodapp在清单层面是一份标准的Manifest V3Chrome 扩展见 manifest.chrome.jsondevtools_page:devtools.html负责向 DevTools 注册 Angular 面板background.service_worker:app/background_bundle.js承载各标签页连接的路由管理content_scripts: 三条在所有帧all_frames: true运行的脚本分别负责检测注入、页面有效性探测与消息桥接permissions:scripting、activeTab、storage、debuggerhost_permissions为all_urls。Safari 的转换工具会为这份 MV3 扩展生成配套的 Xcode App Extension 壳使同样的前端代码在 Safari Web Inspector 中呈现。换句话说面板 UI、消息总线、后端注入逻辑在 Chrome 与 Safari 之间是完全共享的差别仅在于浏览器对扩展宿主的封装方式不同。如果希望在转换之前先确认这份产物本身工作正常也可以在 Chrome 中按常规「Load unpacked」方式加载同一目录验证详见 devtools/README.md——这样能把「构建问题」与「Safari 转换/启用问题」隔离开来排查。五、常见问题排查FAQ结合上文证据将实践中容易踩坑的点汇总如下现象原因与排查方向xcrun提示找不到命令Xcode 未安装或未执行xcode-select切换到命令行工具需要 Xcode 13 完整安装而非仅 CommandLineTools转换/编译时依赖报错未先按 devtools/README.md 在仓库根目录执行pnpm install --frozen-lockfile安装依赖找不到dist/bin/devtools/projects/shell-browser/src/prodapp构建未成功或命令未在仓库根目录执行该目录由 bazelisk 输出路径以仓库根为基准Safari 工具栏无 Angular 图标扩展未在 Safari 设置中启用或页面不是 Angular 应用此时为灰度图标Web Inspector 无 Angular 标签页「Web Inspector Extensions」实验特性未勾选或被测应用非 dev mode生产版不暴露调试钩子代码改动后界面未更新重新执行pnpm devtools:build:chrome并在 Xcode 中重新构建、刷新被测页面六、相关参考文档devtools/docs/safari.md本文对应的官方安装说明内容简洁本文已完整覆盖并展开。devtools/docs/firefox.mdFirefox 端的安装说明——先用pnpm devtools:build:firefox构建再从about:debugging加载临时附加组件流程思路与 Safari 一致可对照理解「一套源码、多浏览器产物」的设计。devtools/README.md仓库级构建/开发/调试与加载说明包括 dev server、debug 构建、sourcemap、Cypress e2e 等。devtools/docs/connection.md讲解扩展在标签页/帧之间如何连接与路由消息面板 - background - content script - backend有助于理解为何面板在 Safari Web Inspector 中同样能工作。devtools/projects/shell-browser/src/BUILD.bazelprodapp组装细节与flag_browser切换逻辑。manifest.chrome.json被 Safari 转换器消费的扩展清单。七、小结Angular DevTools 的 Safari 支持走的是「构建 Chrome 版产物 →safari-web-extension-converter转换 → Xcode 编译 → 在 Web Inspector 启用」的实验性链路。你不需要任何 Safari 专属代码分支只需保证 Xcode 13、仓库依赖完整、构建成功、Safari 实验开关打开以及被测应用运行在开发模式即可在 Safari 中体验与 Chrome DevTools 中相同的 Angular 调试面板。当流程出现问题时按「构建产物Chrome 验证→ 转换工程Xcode→ 扩展启用Safari→ 页面检测dev mode」的顺序逐层定位通常是最有效的方式。【免费下载链接】angularDeliver web apps with confidence 项目地址: https://gitcode.com/GitHub_Trending/an/angular创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考