Skip to content

12. 部署

开发期间,应用程序在 [ng serve] 的控制下运行:即时编译,带有 [Angular] 面向开发者的检查和消息,并在每次修改后重新加载。要部署它,我们要构建它:[ng build] 会生成一个经过优化的、不含任何开发工具的 Web 应用。我们把它部署到 Web 服务器上,同样也是这个应用被 [Capacitor] 打包进 [Android] 应用:两个平台只有一个构建。

12.1. Web 版本

  1. 构建客户端。在 [rdvmedecins_ionic] 文件夹中:
npx ng build

控制台显示(文件列表已截断):

Initial chunk files | Names          |  Raw size | Estimated transfer size
chunk-D1Fy7lNv.js   | -              | 949.39 kB |               177.56 kB
styles-EA54KZY4.css | styles         |  41.82 kB |                 5.04 kB
chunk-Dy0_VL94.js   | -              |  37.92 kB |                13.16 kB
main-FA64HVK2.js    | main           |  35.96 kB |                11.14 kB
...
                    | Initial total  |   1.10 MB |               222.11 kB

Lazy chunk files    | Names          |  Raw size | Estimated transfer size
chunk-CQUKBzMH.js   | my-account     |   6.02 kB |                 1.90 kB
chunk-SZ_YMAdj.js   | login          |   5.43 kB |                 2.04 kB
chunk-keRC2_fg.js   | patient-area   |   4.31 kB |                 1.68 kB
chunk-BcO9UgKs.js   | person-form    |   4.30 kB |                 1.66 kB
chunk-Bs2orSJL.js   | persons        |   3.92 kB |                 1.63 kB
chunk-D3F55gZB.js   | register       |   3.53 kB |                 1.29 kB
chunk-zsTSOYLr.js   | error-page     |   1.15 kB |               647 bytes
...and 11 more lazy chunks files. Use "--verbose" to show all the files.

Application bundle generation complete. [12.778 seconds]

Output location: .../rdvmedecins_ionic/dist/rdvmedecins_ionic

不带任何选项时,[ng build] 使用 [angular.json] 中的 [production] 配置:代码经过优化(名称被缩短,空格和注释被删除,未使用的代码被消除),并且移除了为开发准备的检查。编译器把应用程序([TypeScript]、模板、[Angular]、[Ionic])编译为 [JavaScript],放在 [dist/rdvmedecins_ionic/browser/] 文件夹中:

  • [index.html]:应用程序的页面,它加载 [JavaScript] 文件和样式表。与 [Flutter] 客户端不同,该应用程序生成标准的 HTML 内容,由浏览器自己显示;
  • 启动时加载的初始“块(chunk)”:[Angular]、[Ionic]、路由器、各个服务和布局。1.1 MB,经服务器压缩后约为 220 KB:这就是最后一列中的估计值;
  • “懒加载”片段:每个屏幕一个([login]、[my-account]……),这得益于路由的 [loadComponent] (参见 [app.routes.ts]),以及另外一些按需加载的 [Ionic] 组件。每个片段只在首次访问对应屏幕时下载;
  • 每个文件的名称都包含其内容的哈希值([main-FA64HVK2.js]):服务器可以指示浏览器无限期缓存它们,因为新版本会有新的名称;
  • [i18n/] 和 [favicon.ico]:[public/] 文件夹的内容,原样复制;
  • [angular.json] 为 [production] 配置设置了“限额”:如果初始块超过 2 MB 则发出警告,超过 5 MB 则报错。该应用程序远未达到这些限额。

这里不需要 [--define "SERVER='...'"] 选项:由 JSON 服务器提供服务时,应用程序使用 [config.ts] 的相对路径([/api/...])。

  1. 把它部署到服务器。JSON 服务器可以提供已编译的 Web 客户端(服务器的 [src/web/client-spa.ts] 文件):它在服务器根目录的 [client/] 文件夹中,或在由环境变量 [CLIENT_DIR] 指定的文件夹中查找客户端的文件(服务器文件 [src/config/paths.ts];可以把它写在 [.env] 文件中)。有两种做法:

  2. 把 [dist/rdvmedecins_ionic/browser/] 文件夹的内容复制到 JSON 服务器根目录下的 [client/] 文件夹中([rdvmedecins-nestjs-json/client/index.html]、[rdvmedecins-nestjs-json/client/main-FA64HVK2.js]……);

  3. 或者直接指定由 [ng build] 生成的文件夹:
CLIENT_DIR=../rdvmedecins_ionic/dist/rdvmedecins_ionic/browser

(相对于服务器根目录的路径,或绝对路径)。然后重启服务器。它会显示:

[Nest] LOG [RdvMedecins] web client served from .../rdvmedecins_ionic/dist/rdvmedecins_ionic/browser
[Nest] LOG [RdvMedecins] JSON server started: http://localhost:8080/api

完整的应用程序现在可以通过 http://localhost:8080 访问。服务器提供客户端的文件,并对 /api 之外的任何其他地址返回 [index.html] :重新加载页面 /schedule?doctorId=1&day=2026-10-13 是可行的(由客户端的浏览器显示该地址对应的页面)。页面和 API 来自同一个源:没有 CORS,令牌 Cookie 也会被传递。

要在不停止开发服务器的情况下进行测试,可以在另一个端口上启动 JSON 服务器的一个实例,并在命令行中同时指定这两个变量(这里是在 [Linux] 或 [macOS] 下;在 [Windows] 上使用 [PowerShell] 时,需要先把它们定义为 [$env:PORT=8090] 和 [$env:CLIENT_DIR='...']):

cd rdvmedecins-nestjs-json
PORT=8090 CLIENT_DIR=../rdvmedecins_ionic/dist/rdvmedecins_ionic/browser npm run start:prod

然后即可通过 http://localhost:8090 访问该应用程序;两个实例共享同一个数据库。这个客户端的 Web 版本就是这样测试的:登录、日程、在 /schedule?... 这样的地址上重新加载页面,以及已翻译的标签页标题。

该客户端也可以部署在任何 Web 服务器([nginx]、[Apache]……)上,前提是它把 /api 请求转发给 JSON 服务器(“反向代理”),并对未知的 URL 重定向到 [index.html] :这正是 [ng serve] 在开发期间所做的事情。

12.2. Android 版本

构建 [Android] 应用需要 [Android Studio] 和来自 [Android] 的 SDK(参见“搭建开发环境”一章)。[Capacitor] 8 需要 JDK 21 或更高版本:[Android Studio] 附带的版本即可满足要求。

  1. 一次性创建 [Android] 项目:
npx cap add android

该命令会创建 [android/] 文件夹:一个完整的 [Android Studio] 项目(一个 [Gradle] 项目),其中包含一个显示 [Android] 的 [WebView] 的 Activity,以及应用程序所用的 [Capacitor] 插件([@capacitor/app]、[@capacitor/preferences])。这个文件夹是项目的一部分:请保留它(并与源代码一起用 [git] 保存),因为应用程序的名称、图标和签名都在这里设置。

如果 JDK 是 [Java] 25(较新版本 [Android Studio] 所用的那个),则 [Capacitor] 选定的 [Gradle] 版本(8.14)无法与之配合工作([Unsupported class file major version 69]):我们在 [android/gradle/wrapper/gradle-wrapper.properties] 文件中切换到 [Gradle] 9.1(参见示例 01):

distributionUrl=https\://services.gradle.org/distributions/gradle-9.1.0-all.zip
  1. 构建 Web 应用程序,然后把它复制到 [Android] 项目中:
npx ng build
npx cap sync android
  • 第 1 行:Web 应用程序,位于 [dist/rdvmedecins_ionic/browser/];
  • 第 2 行:[cap sync] 把这个文件夹([webDir] ,来自 [capacitor.config.ts])复制到 [android/app/src/main/assets/public/],同时复制 [Capacitor] 的配置([capacitor.config.json]),并更新各插件。当 [server.cleartext] 设为 [true] 时,它还会在插件清单中添加 [android:usesCleartextTraffic="true"] 属性,该清单在构建时会与应用程序的清单合并:这样就允许向开发服务器发送 [http://](未加密)请求。

每次修改应用程序代码之后,都必须重新运行这两条命令。

  1. 运行:
npx cap run android

该命令会列出可用的设备(在 [Android Studio] 中创建的模拟器,以及通过 USB 连接并启用“USB 调试”的手机),构建应用程序,把它安装到所选设备上并启动它。你也可以在 [Android Studio] 中打开该项目([npx cap open android])并使用其“Run”按钮。

在模拟器上,应用通过地址 [http://10.0.2.2:8080] 连接到服务器(参见 [config.ts])。在与电脑连接到同一个 Wi-Fi 网络的真机上,你必须使用如下语法向它提供电脑在该网络中的地址(在 [ipconfig] 下,[Windows] 中):

1
2
3
npx ng build --define "SERVER='http://192.168.1.20:8080'"
npx cap sync android
npx cap run android

电脑的防火墙必须允许 8080 端口的传入连接。

  1. 测试。该应用程序是由 [WebView] 显示的网页:电脑上 [Chrome] 的开发者工具可以检查它。打开地址 [chrome://inspect]:模拟器或手机上的应用程序会出现在那里;“Inspect”会打开控制台、元素检查器和“Network”选项卡(由于对 API 的请求经过 [CapacitorHttp]——也就是经过原生代码——它们在那里不像在 Web 上那样容易看到:[Logcat] 的控制台,位于 [Android Studio] 中,会显示它们)。

  2. 调试安装文件(APK)。在 [Android Studio] 中:“Build > Generate App Bundles”或“APKs > Generate APKs”。或者通过命令行,在 [android/] 文件夹中:

cd android
./gradlew assembleDebug

(在 [Windows] 下:[gradlew assembleDebug])。文件生成在 [android/app/build/outputs/apk/debug/app-debug.apk]。它使用 [Android Studio] 的调试密钥签名:用于测试已经足够。可以通过 [adb install app-debug.apk] 将其安装到已连接的手机上,或者把文件复制到手机上并打开它([Android] 随后会提示你允许安装来自“未知来源”的应用)。

  1. 已签名的生产版本。发布的应用必须使用开发者专属的密钥签名,并且必须妥善保管该密钥(所有更新都必须使用同一个密钥签名):

  2. 在 [Android Studio] 中:使用“Build > Generate Signed App Bundle or APK...”菜单,它同样可以用来创建密钥(一个受密码保护的“keystore”文件);

  3. 或者通过命令行:使用 JDK 的 [keytool] 工具创建密钥,然后构建已签名的版本:
keytool -genkey -v -keystore rdvmedecins.jks -keyalg RSA -keysize 2048 -validity 10000 -alias rdvmedecins
npx cap build android --keystorepath ../rdvmedecins.jks --keystorepass password --keystorealias rdvmedecins --keystorealiaspass password --androidreleasetype APK --signing-type apksigner
  • 第 1 行:在 [rdvmedecins.jks] 文件中创建密钥(该命令会提示输入开发者姓名、组织等);
  • 第 2 行:[cap build] 启动“release”版本的 [Gradle] 构建([assembleRelease]),并用这个密钥为生成的文件签名(密钥路径相对于 [android/] 文件夹)。[--signing-type apksigner]:签名由 SDK 的 [apksigner] 工具创建,其所在文件夹 [build-tools/<version>] 必须位于 PATH 中;如果没有这个选项,[Capacitor] 会使用 [jarsigner],而对于 APK,较新版本的 [Android] 已不再接受其签名。[--androidreleasetype AAB] 会生成“Android App Bundle”,这是 [Google Play Store] 所要求的格式。

你也可以在 [android/app/build.gradle] 文件中描述签名(一个 [signingConfigs] 块;参见 [Android] 文档中题为“Sign your app”的部分),然后直接运行 [./gradlew assembleRelease](得到一个 APK,位于 [android/app/build/outputs/apk/release/])或 [./gradlew bundleRelease] (得到一个 App Bundle)。密钥的密码不得写入与源代码一起保存的文件中。

  1. 对于真正的发布:

  2. 应用程序名称设置在 [capacitor.config.ts] ([appName])和 [android/app/src/main/res/values/strings.xml] 中;其图标设置在 [android/app/src/main/res/mipmap-*/] 文件中([@capacitor/assets] 工具可以从一张图片生成所有这些文件);

  3. 服务器必须使用 HTTPS(因为要传输密码):我们从 [server.cleartext] 中移除 [capacitor.config.ts],并使用服务器的公开地址构建应用程序([--define "SERVER='https://rdvmedecins.example.com'"])。

12.3. 生产服务器

在实际的生产环境中,别忘了服务器上的 [.env] 文件:

  • 一个长而随机的 [JWT_SECRET];
  • 一个为空的 [CAPTCHA_TEST];
  • [COOKIE_SECURE=true] 如果站点通过 HTTPS 提供服务(必须如此):此时 Cookie 只会通过加密连接传输;
  • [TRUST_PROXY=true] 如果服务器位于代理([nginx]……)之后,以便尝试次数限制能看到客户端的真实 IP 地址。

服务器无需声明任何 CORS 规则:在 Web 上,客户端由服务器自身提供(同源);在 [Android] 上,请求来自原生代码([CapacitorHttp]),CORS 对它不适用。

然后我们启动已编译的服务器:[npm run build],接着是 [npm run start:prod]。