Frequently Asked Questions（常见问题）

Q: "Safari Extension State Unknown" or the extension does not show in Safari

Q：扩展显示为上述状态 或 Safari 设置中未显示该扩展项

We've seen several users experience this issue, and it appears to be an upstream issue, but thanks to @djpadz for tried, we now have a simple workaround:
我们看到有几个用户遇到该问题，它似乎是一个上游问题，但感谢 @djpadz 的尝试，我们现在有一个简单的解决方法：

• Quit Safari, then open the macOS Terminal app paste and run the following command, done. [ref]
• 退出 Safari，然后打开 macOS 的 终端 应用粘贴并运行下面的命令，完成。

/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -f -R /Applications/Safari.app

Other possible scenarios:

• Can't install this extension because Safari Extension Disabled #893 (comment)

Q: Script cannot be injected due to the Content Security Policy (CSP) of the page or site

Q：由于页面或站点的内容安全策略 (CSP)，无法注入脚本

Sorry, currently we don't have a way to bypass CSP protection in Safari due to strict extension API restrictions and lack thereof.
For injecting page contexts, there is nothing we can do at the moment, but if your case allows it, try to use content scripts contexts for your user scripts, please refer to: #106 (comment)
抱歉，当前我们没有办法在 Safari 中绕过 CSP 保护由于严格的扩展 API 限制和缺失。
对于注入页面上下文，当前我们没有什么可以做的，但是如果您的案例允许，尝试使用内容脚本上下文来实现您的用户脚本，请参考：#106 (comment)

Q: Unable to enable extensions, extensions are grayed out in Safari settings. (#678)

Q：无法启用扩展，在 Safari 设置中扩展呈现灰色无法点击。(#678)

Please check if you have the following restrictions turned on:

Settings > Screen Time > Content & Privacy Restrictions

If you have this setting turned on, check the setting in:

Store, Web, Siri & Game Center Content > Web Content

Make sure it is set to "Unrestricted" or you won't be able to use any Safari Extensions.

How to Review Error Logs（如何查看错误日志）

Since this extension respects user privacy and does not collect any usage information, when you encounter errors or report issues, you may need to review and provide error logs to help us locate and solve your issues. Here's how to view the different parts of the error logs.
由于此扩展尊重用户隐私，未收集任何使用信息，当您遇到错误或报告问题时，您可能需要查看和提供错误日志以帮助我们定位和解决您的问题。以下是查看不同部分错误日志的方法。

The Extension/App is made up of several parts that work together:
该 扩展/App 由几个部分协同运行：

• Native application（本地应用）

  • In this part, you need to review the error logs through the console application of the macOS system.
  • 此部分您需要通过 macOS 系统 控制台 应用来查看错误日志。
  • Once feat: local native logger and better OOBE #761 is released, you will be able to export logs via the built-in Logger feature.
    • You could already use this feature through the latest beta version
    • Install beta version (Refer to the videos in feat: local native logger and better OOBE #761 for next steps)
    • Turn on logger in settings (iOS) or menu item (macOS)
    • Repeat the operation process you have in issues
    • Export log in app
  • 一旦 feat: local native logger and better OOBE #761 发布，您将可以通过内置 Logger 功能来导出日志。
    • 您已经可以在最新测试版中使用该功能
    • 安装 beta 版应用（后续步骤可参考 feat: local native logger and better OOBE #761 中的视频）
    • 在设置（iOS）或菜单项（macOS）中启用本地 Logger
    • 重复产生错误的步骤流程
    • 在 App 中导出日志

• Safari extension（Safari 扩展）

  • background page（背景页面）

    • You need to Show "Develop" menu in Safari Preferences, then open the background page inspector from this menu.
    • 您需要在 Safari 设置中显示“开发”菜单，然后从此菜单中打开背景页面检查器。

  • popup page（弹出页面）

    • You need to open the popup and then open the web inspector via the context menu (Inspect Element) in popup page.
    • 您需要点开弹出页面，然后通过页面中的上下文菜单（检查元素）打开网页检查器。

  • extension page（扩展页面）

    • You need to open the extension page, then click "Show JavaScript Console" from the "Develop" menu or use the shortcut key ⌥ ⌘ C to open the console.
    • 您需要打开扩展页面，然后从“开发”菜单中点击“显示JavaScript控制台”或使用快捷键 ⌥ ⌘ C 打开控制台。

  • content scripts and user scripts（内容脚本 和 用户脚本）

    • You need to open the site where the script matches, then click "Show JavaScript Console" from the "Develop" menu or use the shortcut key ⌥ ⌘ C to open the console.
    • 您需要打开脚本匹配的网站，然后从“开发”菜单中点击“显示JavaScript控制台”或使用快捷键 ⌥ ⌘ C 打开控制台。

@quoid explained how to review error logs through a more detailed graphic introduction in some issues:
@quoid 在一些 Issues 中通过更详细的图文介绍解释了如何检查错误日志：
#245 (comment) , #201 (comment)

You can also refer to Apple's developer documentation:
您还可以参考 Apple 的这篇开发文档：
Troubleshooting your Safari web extension