1. 问题现象与初步排查
在尝试将 vaadin web 应用程序部署到 apache tomcat 服务器时，开发者可能会遇到应用程序无法访问，浏览器显示 404 not found 错误的情况。尽管 tomcat 服务器本身运行正常，且其他非 vaadin 应用可能可以正常访问，但 vaadin 应用的特定路径（例如 /your-app-name/）却无法解析。
典型的服务器访问日志可能会记录如下错误：
127.0.0.1 - - [15/Nov/2022:11:02:51 -0500] GET /icsprojects-version-1.0/ HTTP/1.1 404 783 127.0.0.1 - - [15/Nov/2022:11:18:00 -0500] GET /icsprojects-version-1.0/ HTTP/1.1 404 783
这些日志条目明确指出，当尝试访问部署的 Vaadin 应用程序路径时，服务器返回了 404 状态码，表示资源未找到。
在遇到此类问题时，开发者通常会进行以下初步排查：
- 确认 WAR 包完整性：检查 Vaadin 项目是否已正确打包为 .war 文件，并且该文件包含了所有必要的类和资源。
- 部署方式检查：确保 WAR 文件已通过 Tomcat Manager 界面成功部署，或直接放置在 Tomcat 的 webapps 目录下并等待其自动解压和部署。
- 构建工具检查：无论使用 Gradle 还是 Maven，都已仔细审查 pom.xml 或 build.gradle 文件，确保 Vaadin 依赖和构建配置正确无误。
- 尝试部署不同应用：尝试部署自定义 Vaadin 应用和社区提供的 Vaadin 示例应用，结果均出现相同问题。
尽管进行了这些排查，问题依旧存在，这表明可能存在更深层次的兼容性问题。
2. 核心原因：Java EE 与 Jakarta EE 的兼容性鸿沟
导致 Vaadin 应用在某些 Tomcat 版本上部署失败的根本原因，在于 Java EE (Java Platform, Enterprise Edition) 和 Jakarta EE (Jakarta Enterprise Edition) 之间的包名和规范变更。
- *Java EE (javax.)*：传统的 Java EE 规范，包括 Servlet、JSP、EJB 等 API，其核心包名以 `javax.开头。例如，Servlet API 的包是javax.servlet`。
- *Jakarta EE (jakarta.)*：随着 Java EE 捐赠给 Eclipse 基金会并更名为 Jakarta EE，为了避免与 Oracle 现有的 `javax.包冲突，所有相关的 API 包名都从javax.更改为jakarta.。例如，Servlet API 的包现在是jakarta.servlet`。
Apache Tomcat 的版本兼容性：
- Tomcat 9 及更早版本：这些版本实现了 Java EE 8 及更早的规范，因此它们期望应用程序使用 javax.* 包。
- Tomcat 10 及更高版本：这些版本实现了 Jakarta EE 9 及更高版本规范，因此它们期望应用程序使用 jakarta.* 包。
Vaadin 框架的兼容性：
- Vaadin 14 及更早版本：这些版本是基于 Java EE (使用 javax.* 包) 构建的。
- Vaadin 23 及更高版本：这些版本已迁移到 Jakarta EE (使用 jakarta.* 包)，并需要兼容 Jakarta EE 的 Servlet 容器。
问题症结： 当您尝试将一个基于 Java EE (使用 javax.* 包) 的 Vaadin 应用（如 Vaadin 14）部署到 Tomcat 10 或更高版本时，Tomcat 无法找到应用程序所需的 javax.* 包和 API。这导致应用程序无法正确初始化，从而在访问时返回 404 错误，因为 Web 容器未能识别并加载该应用。
3. 解决方案与部署策略
针对上述兼容性问题，有以下几种解决方案：
3.1 方案一：降级 Apache Tomcat 版本
最直接和简单的解决方案是使用与您的 Vaadin 版本兼容的 Tomcat 版本。
- 如果您的 Vaadin 应用是基于 Java EE (Vaadin 14 或更早版本)，请使用 Apache Tomcat 9 或更早版本。
- 下载并安装相应版本的 Tomcat，然后按照标准的 WAR 包部署流程进行操作。
3.2 方案二：升级 Vaadin 版本（如适用）
如果项目允许且有资源进行迁移，可以考虑将 Vaadin 应用升级到支持 Jakarta EE 的版本（Vaadin 23 及更高版本）。
- 升级 Vaadin 版本通常涉及更新项目依赖、调整代码以适应新版本 API 的变化，并确保所有第三方库也与新的 Vaadin 和 Jakarta EE 环境兼容。
- 升级后，您的 Vaadin 应用将能够与 Tomcat 10+ 及其实现的 Jakarta EE 规范无缝协作。
3.3 方案三：使用嵌入式 Web 服务器（推荐 Spring Boot）
对于学校项目或需要快速部署的场景，使用 Spring Boot 及其内置的嵌入式 Web 服务器（如 Tomcat、Jetty 或 Undertow）是一种非常简便且强大的解决方案。
优点：
- 简化部署：无需单独安装和配置外部 Tomcat 服务器，应用程序可以打包成一个可执行的 JAR 文件，直接运行。
- 消除兼容性问题：Spring Boot 会自动管理其嵌入式服务器的版本和依赖，通常能够很好地处理 Vaadin 应用的兼容性。
- 易于开发和测试：开发过程中可以直接通过 IDE 运行应用，无需部署到外部服务器。
Spring Boot 示例配置： 在您的 Vaadin 项目中，如果使用 Maven，可以在 pom.xml 中添加 Spring Boot Web Starter 依赖。
com.vaadin vaadin-spring-boot-starter org.springframework.boot spring-boot-starter-web org.springframework.boot spring-boot-starter-test test org.springframework.boot spring-boot-maven-plugin
然后，创建一个 Spring Boot 主应用程序类：
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class YourVaadinApplication {
public static void main(String[] args) {
SpringApplication.run(YourVaadinApplication.class, args);
}
}通过这种方式，您可以将 Vaadin 应用打包为可执行 JAR，并通过 java -jar your-app.jar 命令直接运行，而无需担心外部 Tomcat 的版本兼容性问题。
4. 部署注意事项与最佳实践
-
详细日志分析：在部署过程中，务必仔细检查 Tomcat 的日志文件（如 catalina.out、localhost.
.log 或 manager. .log）。这些日志通常会提供关于部署失败原因的详细堆栈跟踪信息，例如类加载错误、找不到特定包等，这对于诊断问题至关重要。 - 上下文路径：确保您在访问 Vaadin 应用时使用的 URL 与其在 Tomcat 中部署的上下文路径（Context Path）相匹配。例如，如果 WAR 文件名为 my-app.war，通常可以通过 http://localhost:8080/my-app/ 访问。
- 内存与资源：确保 Tomcat 有足够的内存来运行 Vaadin 应用程序，尤其是在开发环境中。Vaadin 应用可能比简单的静态页面消耗更多资源。
- 安全性：对于生产环境，应配置 Tomcat 的安全性，包括用户认证、SSL/TLS 加密等。如果使用 ngrok 进行隧道传输，也要考虑其安全性配置。
- 持续集成/持续部署 (CI/CD)：对于更复杂的项目，考虑采用 CI/CD 流程自动化构建、测试和部署 Vaadin 应用，以减少手动错误并提高效率。
总结
Vaadin 应用在 Apache Tomcat 上的 404 部署错误，核心在于 Java EE 和 Jakarta EE 规范之间的不兼容性，尤其是 javax.* 和 jakarta.* 包的冲突。理解这一背景是解决问题的关键。通过选择合适的 Tomcat 版本（Tomcat 9 及更早版本），或升级 Vaadin 到支持 Jakarta EE 的版本，或采用 Spring Boot 嵌入式服务器，开发者可以有效地解决这些兼容性挑战。对于大多数现代项目，尤其是那些追求部署简便性的项目，Spring Boot 的嵌入式服务器方法通常是更优选的解决方案。
