Quarkus-Omnifaces扩展中manifest.json无法识别问题求助

我在 Quarkus + MyFaces 应用中配置了 PWAResourceHandler，调试时能确认清单文件已生成，但系统始终无法识别它。使用的版本信息：

• Quarkus 2.16.3.Final
• Quarkus-Omnifaces 3.14.3

相关实现代码：

@ApplicationScoped
public class AppHandlerPWA extends WebAppManifest {

    @Override
    public String getName() {
        return "AgroV ERP";
    }

    @Override
    public String getShortName() {
        return "AGROV";
    }

    @Override
    public Collection<ImageResource> getIcons() {
        return Arrays.asList(
                ImageResource.of("images/pwa/agrov-icon-144x144.png", Size.SIZE_144),
                ImageResource.of("images/pwa/agrov-icon-180x180.png", Size.SIZE_180),
                ImageResource.of("images/pwa/agrov-icon-180x180.png", Size.SIZE_512)
        );
    }

    @Override
    public String getThemeColor() {
        return "#cc9900";
    }

    @Override
    public String getBackgroundColor() {
        return "#ffffff";
    }

    @Override
    public Display getDisplay() {
        return Display.STANDALONE;
    }

    @Override
    public Collection<Category> getCategories() {
        return Arrays.asList(Category.BUSINESS, Category.FINANCE);
    }

    @Override
    public String getOfflineViewId() {
        return "/webapp/public/offline.html";
    }

    @Override
    public Collection<String> getCacheableViewIds() {
        return Arrays.asList(
                "/webapp/public/login.xhtml"
        );
    }

    @Override
    public Collection<RelatedApplication> getRelatedApplications() {
        return Arrays.asList(
                RelatedApplication.of(Platform.PLAY, "https://play.google.com/store/apps/details?id=com.example.app1", "com.example.app1"),
                RelatedApplication.of(Platform.ITUNES, "https://itunes.apple.com/app/example-app1/id123456789")
        );
    }
}

排查与解决建议 #

• 确认页面manifest链接：检查根页面（如index.xhtml）是否包含 <link rel="manifest" href="/manifest.json">。OmniFaces通常会自动注入该标签，但Quarkus环境下可能存在拦截优先级问题，手动添加可排除此问题。
• 验证manifest可访问性：直接访问http://<你的应用地址>/manifest.json，确认能返回正确JSON内容，同时检查响应头的Content-Type是否为application/manifest+json。如果返回404或类型错误，需调整Quarkus静态资源配置或OmniFaces资源处理器路径。
• 检查Quarkus静态资源配置：在application.properties中确认quarkus.http.static-resources.paths包含manifest及图标资源所在目录，避免Quarkus优先拦截资源请求导致OmniFaces无法处理。
• 核对版本兼容性：确认Quarkus-Omnifaces 3.14.3与Quarkus 2.16.3.Final的适配性，查看官方文档或issue列表是否存在已知的PWA处理器兼容问题。
• 校验资源路径正确性：检查getIcons()、getOfflineViewId()中配置的资源路径是否与实际文件位置一致，路径错误会导致PWA处理器无法正常生成完整的manifest内容。
• 查看应用日志：启动应用时观察Quarkus日志，是否有PWAResourceHandler初始化失败、资源找不到等警告或错误信息，这些日志能直接定位问题根源。

内容的提问来源于stack exchange，提问作者Felipe Miranda