VS2022C#跨平台开发Avalonia快速入门

目前项目能在 Windows 和 Linux 两边都跑起来了。桌面界面用的是 Avalonia，后端是 .NET（有用到 .NET6，也准备兼容更高版本的运行时），数据库在 Linux 上跑着 SQL Server，整个服务由 systemd 管理，外面还用 Nginx 做反向代理。部署过程中遇到的问题和处理方法都记录在下面，按时间线倒过来讲，方便看清每一步是怎么推进的。

最后一步是把发布好的 .NET6 程序放到服务器上，然后用 systemd 启动。发布用 dotnet publish -c Release -o /var/www/myapp，这样把所有 DLL 和依赖都打到一个目录。把这目录通过 SFTP 或宝塔面板的文件管理上传到服务器，目录权限要给好，www-data 或者运行服务的用户需要有读写权限。随后在 /etc/systemd/system 下写一个 myapp.service，ExecStart 指向 /usr/bin/dotnet /var/www/myapp/MyApp.dll，设置 Restart=always，User 指定那个运行账户。写好后执行 systemctl daemon-reload，systemctl enable –now myapp。这个流程一气呵成的话，程序就能随着系统启动自动起来，日志可以在 journalctl -u myapp 查看。用宝塔面板部署时，先在面板建站，文件上传到站点目录，然后在面板的反代设置里把域名反代到 127.0.0.1:5000（或你设置的 Kestrel 端口），注意宝塔的防火墙和 Nginx 配置要放通这些端口。

在服务起来之前，有个关键环节是数据库。要在 Linux 上装 SQL Server，过程要稳妥。以 Ubuntu 为例，先导入 Microsoft 的 GPG key，添加 mssql-server 的源，apt update，然后 apt install -y mssql-server。安装后运行 sudo /opt/mssql/bin/mssql-conf setup，按提示选择版本、设置 SA 密码。安装完成后 systemctl start mssql-server，systemctl enable mssql-server。确认端口 1433 通了，必要时 ufw allow 1433。连接通过 sqlcmd 或者客户端工具测试，如果是远程连接要在 SQL Server 配置里打开 TCP/IP 并重启服务。部署期间常见的问题有密码不符合复杂性规则、端口被占用、或者内存不足（SQL Server 占用必定内存，需要预留），这些都要一条条排查。

在把后端部署到 Linux 之前，接口的构建和测试是在本地完成的。WebApi 基于 .NET6 写的，项目里要注意发布配置：在 csproj 里设置 Self-contained 或 Framework-dependent，根据服务器是否装了目标运行时决定。一般我会选择 framework-dependent，这样体积小，但要在服务器上预先安装对应的 .NET 运行时（可以用 apt 安装 dotnet-runtime 或用 Microsoft 的 repo）。本地调试时用 Kestrel 监听 0.0.0.0:5000，确认 API 路由、跨域、连接字符串正常，再打包发布。对于连接 SQL Server，需要把连接字符串改成服务器地址，注意防止把本地开发账号直接暴露到生产环境里。

桌面端选用了 Avalonia，从 UI 到最终打包也走了几步。Avalonia 是一个基于 .NET 的跨平台 UI 框架，支持 Windows、Linux、macOS，用 XAML+ C# 写界面。它的优势在于跨平台一致性强，样式和控件比较灵活，企业级桌面工具、跨平台客户端、需要多端部署的软件都很适合。Avalonia 的代码托管在 GitHub（
https://github.com/AvaloniaUI/Avalonia），社区活跃，文档和示例能帮新人上手。Linux 版本的支持已经成熟，可以直接打包成 .deb 或 AppImage，在不同发行版上部署都比较方便。我的尝试里，使用 Avalonia 后 UI 行为在三大桌面系统上差异小，调试效率比起分别做 WinForms、GTK、Cocoa 要高不少。说句偏感性的，跨平台省了不少重复造轮子的力气。

要在 Visual Studio 2022 上开发并打包 Avalonia 项目，需要先把 VS 环境准备好。安装 Visual Studio 2022 时，我在单个组件页里勾选了几个必须的选项：.NET 8.0/9.0 运行时（为了兼容未来的运行环境）、.NET Framework 4.8 SDK（部分老项目或工具链需要）、Windows 10/11 SDK（做 Windows 打包和测试必须有）。这些组件能保证本地调试、打包和运行时检查不会缺依赖。安装时如果网速慢，分批安装也行，但有时会由于缺少 SDK 导致发布失败，所以一次性把关键组件装齐比较稳。

装好 VS 之后，再装 Avalonia 的 VS 扩展。打开 VS2022，扩展 → 管理扩展，搜索 “Avalonia for Visual Studio”，下载安装并重启。扩展安装后会增加模板和 XAML 编辑支持，创建项目更方便。缺了这个扩展，虽然可以用命令行 dotnet new avalonia.app，但在 VS 里缺少设计器支持，体验差点。另一个常用步骤是安装 Avalonia 的模板，命令是 dotnet new -i Avalonia.Templates，这样能快速用 dotnet new 创建不同类型的项目。开发时要留意控件的渲染差异，Linux 下部分字体、图标可能需要额外处理。

有一部分需求是让原本基于 WinForm 的串口通讯程序能跨平台运行，这是用 GtkSharp 的方向来实现的。核心逻辑是把与设备通讯的那部分用 System.IO.Ports（或 NuGet 的 System.IO.Ports 包）抽离出来，这部分在 .NET Core/.NET 6 在 Linux 下可以通过 /dev/ttyS* 或 /dev/ttyUSB* 访问。界面层从 WinForm 换成 GtkSharp，GtkSharp 可以在 Linux、Windows、macOS 上运行，UI 控件和事件机制需要重写，信号与回调要适配。测试过程中要注意设备权限：在 Linux 上访问串口一般需要把运行账户加入 dialout 组，或者给设备文件更宽松的权限。调试串口通讯时，先在命令行用 minicom 或 picocom 确认设备能正确收发，再在程序里复现协议。串口参数（波特率、数据位、校验、停止位、流控）必定要和设备一致，掉包或乱码常常由于这些设置有一项不对。

关于把 VOL.NET6 项目用宝塔部署的整个流程，这是个比较完整的操作链。先在本地把项目发布：dotnet publish -c Release -o publish_dir，然后把 publish_dir 上传到宝塔服务器的某个站点目录或自建目录。宝塔面板操作上，文件上传后需要在面板上设置站点的反向代理，把域名指向内网的 Kestrel 端口。为了可管理性，提议依旧用 systemd 管理后台进程，把 dotnet 程序注册成服务。数据库连接要指向服务器上的 SQL Server，并确保防火墙规则允许内网访问。部署后常见问题包括权限不足、环境变量未设置、运行时缺少库，遇到这些一般看 journalctl、dotnet –info、检查 ldconfig 和 libc 相关依赖即可。宝塔能让文件管理、反代、SSL 证书申请这些操作变得可视化，但底层问题还是要进终端排查。

回头说说整个背景和起因：项目最初是 Windows 的桌面+服务器架构，后来业务要求扩展到 Linux 环境，数据库也要统一到服务器上运行，为了减少重复开发，决定选用 Avalonia 做前端跨平台、后端用 .NET6 并尽量统一部署流程。由于团队里有人熟悉宝塔面板，也习惯用 systemd 管理服务，部署方案就沿着这些既有习惯来定。过程中最大的挑战是串口设备在 Linux 下的权限与路径差异、以及 SQL Server 在 Linux 上的资源占用和配置细节，这些都需要在上线前充分测试。

工程里目前主要能做的事：开发环境在 Windows 上用 VS2022、Avalonia 扩展做界面和逻辑；后端用 .NET6 开发，能编译到 Linux 并通过 systemd 启动；数据库在 Linux 上跑 SQL Server；在宝塔面板上可以完成文件上传、反向代理和证书配置。日志和监控则依赖系统工具和应用内日志，调试信息保持详尽，方便排查。下一步会把 CI/CD 接入，把打包、发布和重启服务流程自动化，但这属于另一个话题。