WSL 容器网络模式详解ContainerNetworkingMode 枚举None / Bridged的取值、校验与实战【免费下载链接】WSLWindows Subsystem for Linux项目地址: https://gitcode.com/GitHub_Trending/ws/WSL导读ContainerNetworkingMode是 WSL 容器 SDKWSLC / Microsoft.WSL.Containers中用于声明容器网络接入方式的枚举类型它在 WinRT、C/WinRT、C# 与 C API 四套投影中保持一致None隔离、无网络与Bridged桥接、接入主机网络。本文以 cpp/enumerations/containernetworkingmode.md 为核心结合 wslcsdk.idl 的枚举定义、ContainerSettings.cpp 的严格校验逻辑与 WslcSdkWinRTTests.cpp 的端到端测试完整说明该枚举的底层数值、语义差异、设置方式、与端口映射的交互规则以及注意事项。读完本文你将能在自己的 WSLC 应用或wslc命令行流程中正确选择并设置容器网络模式。枚举定义两个取值两种网络形态ContainerNetworkingMode在 WinRT 投影中的定义位于 wslcsdk.idlnamespace Microsoft.WSL.Containers { enum ContainerNetworkingMode { None 0, Bridged 1, }; }底层 C 枚举定义于 wslcsdk.h语义注释更明确typedef enum WslcContainerNetworkingMode { WSLC_CONTAINER_NETWORKING_MODE_NONE 0, // No networking / isolated WSLC_CONTAINER_NETWORKING_MODE_BRIDGED 1 } WslcContainerNetworkingMode;WinRT 枚举值C 枚举值底层值语义ContainerNetworkingMode::NoneWSLC_CONTAINER_NETWORKING_MODE_NONE0无网络 / 隔离容器内不创建网络接口ContainerNetworkingMode::BridgedWSLC_CONTAINER_NETWORKING_MODE_BRIDGED1桥接模式容器接入主机网络可配合端口映射对外提供服务从源码结构看该枚举刻意保持精简当前 WSL 容器 SDK 只开放「完全隔离」与「桥接」两种形态其余 WSL 发行版级网络模式如 NAT / Mirrored属于 WSL 设置应用与 .wslconfig 体系 的范畴与容器级枚举相互独立使用时不要混淆。严格校验只有 None 与 Bridged 会被接受关联文档明确指出winrt_ContainerSettings.cpp只显式校验None与Bridged两个值。对应的实现位于 ContainerSettings.cpp 的NetworkingMode属性 settervoid ContainerSettings::NetworkingMode(winrt::Windows::Foundation::IReferencewinrt::Microsoft::WSL::Containers::ContainerNetworkingMode const value) { if (m_containerSettings) { throw winrt::hresult_illegal_state_change(LCannot change networking mode after container has been initialized); } if (value value.Value() ! ContainerNetworkingMode::None value.Value() ! ContainerNetworkingMode::Bridged) { throw winrt::hresult_invalid_argument(LInvalid networking mode); } m_networkingMode value; }这段代码揭示了三条重要规则取值白名单任何既不是None也不是Bridged的数值包括强转的非法值如static_castContainerNetworkingMode(99)都会抛出hresult_invalid_argument即E_INVALIDARGHRESULT0x80070057。该行为已被单元测试直接覆盖VERIFY_THROWS_HR(containerSettings.NetworkingMode(static_castWSLCSDK::ContainerNetworkingMode(99)), E_INVALIDARG)见 WslcSdkWinRTTests.cpp。不可变约束属性类型是IReferenceContainerNetworkingMode可空引用类型一旦设置过任何容器设置并完成底层结构转换ToStructPointer见 ContainerSettings.cpp再次修改会抛出hresult_illegal_state_change。因此网络模式必须在创建容器之前确定。允许空值value为nullptr时不做校验表示未显式指定由 SDK 使用默认行为。设置最终通过 WslcSetContainerSettingsNetworkingMode 写入 C 层结构WinRT 值会static_cast为WslcContainerNetworkingMode后传递见 ContainerSettings.cpp 与 wslcsdk.cpp 中的双向映射。两种模式的实际行为差异eth0 是否存在的端到端验证None与Bridged的差别在运行态可以直接观察桥接模式下容器内会出现eth0网络接口隔离模式下则没有。这一结论并非推测而是由 WslcSdkWinRTTests.cpp 中的ContainerNetworkingMode测试用例用debian:latest镜像端到端验证的// BRIDGED: eth0 interface must be present. { auto output RunContainerAndWaitForExit( Ldebian:latest, {.commandLine {L/bin/sh, L-c, L[ -d /sys/class/net/eth0 ] echo HAS_ETH0 || echo NO_ETH0}, .networkingMode WSLCSDK::ContainerNetworkingMode::Bridged}); VERIFY_ARE_EQUAL(output.StandardOutput, LHAS_ETH0\n); } // NONE: eth0 interface must not be present. { auto output RunContainerAndWaitForExit( Ldebian:latest, {.commandLine {L/bin/sh, L-c, L[ -d /sys/class/net/eth0 ] echo HAS_ETH0 || echo NO_ETH0}, .networkingMode WSLCSDK::ContainerNetworkingMode::None}); VERIFY_ARE_EQUAL(output.StandardOutput, LNO_ETH0\n); }据此可以将两种模式总结为None隔离容器完全断开外部网络适合离线计算、严格隔离的安全场景没有eth0因此也无法配合端口映射对外暴露服务。Bridged桥接容器获得网络接口并接入主机网络配合PortMappings可以将容器端口映射到 Windows 侧供宿主机或其他机器访问。在 C/WinRT 中设置网络模式关联文档给出的最小调用方式为containerSettings.NetworkingMode(ContainerNetworkingMode::Bridged);在 C/WinRT 投影中NetworkingMode属性的真实类型是winrt::Windows::Foundation::IReferenceContainerNetworkingMode因此官方 ContainerSettings 文档 提供了完整的初始化写法含端口映射与卷配置可以直接复制使用using namespace winrt::Windows::Foundation::Collections; ContainerSettings containerSettings{ Ldemo-image:latest }; containerSettings.Name(Ldemo-container); containerSettings.NetworkingMode( winrt::box_value(ContainerNetworkingMode::Bridged) .aswinrt::Windows::Foundation::IReferenceContainerNetworkingMode()); containerSettings.HostName(Ldemo-host); containerSettings.DomainName(Llocaldomain); containerSettings.EnableAutoRemove(false); containerSettings.EnableGpu(false); containerSettings.Privileged(false); auto ports single_threaded_vectorContainerPortMapping(); ports.Append(ContainerPortMapping{ 8080, 80, PortProtocol::TCP }); containerSettings.PortMappings(ports); auto volumes single_threaded_vectorContainerVolume(); volumes.Append(ContainerVolume{ LC:\\src, L/src, false }); containerSettings.Volumes(volumes); auto namedVolumes single_threaded_vectorContainerNamedVolume(); namedVolumes.Append(ContainerNamedVolume{ Lcache, L/cache, false }); containerSettings.NamedVolumes(namedVolumes);设置完成后再通过Session::CreateContainer(containerSettings)创建容器并调用container.Start()启动。网络模式与端口映射的交互约束NetworkingMode不是孤立存在的选项它与PortMappings存在强约束关系相关行为同样有测试佐证见 WslcSdkWinRTTests.cppNone 端口映射 → 创建即失败为None模式的容器配置PortMappings会在CreateContainer时抛出E_INVALIDARGauto containerSettings WSLCSDK::ContainerSettings(Ldebian:latest); containerSettings.NetworkingMode(WSLCSDK::ContainerNetworkingMode::None); containerSettings.PortMappings(winrt::single_threaded_vectorWSLCSDK::ContainerPortMapping( {WSLCSDK::ContainerPortMapping(12342, 8000, WSLCSDK::PortProtocol::TCP)})); VERIFY_THROWS_HR(m_defaultSession.CreateContainer(containerSettings), E_INVALIDARG);Bridged 端口映射 → 服务可达桥接模式下容器内的 HTTP 服务可以通过 Windows 侧端口访问测试中先在容器内启动python3 -m http.server 8000再从宿主机请求http://127.0.0.1:12341并断言返回 200。可选绑定地址ContainerPortMapping还支持通过WindowsAddress绑定到指定 IPv4如127.0.0.1或 IPv6如::1地址实现更精细的暴露范围控制。真实样例WSLC-NextCloud 中的应用仓库自带的 WSLC-NextCloud 示例 是Bridged模式的直接落地参考它通过NetworkingMode ContainerNetworkingMode.BridgedProgram.cs配合端口映射将容器内的 Web 服务暴露给 Windows 宿主机访问完整演示了「桥接网络 端口映射」的标准组合套路。跨语言投影与相关文档索引该枚举在仓库的 API 参考文档中覆盖了四套投影口径完全一致可按需查阅C 枚举参考cpp/enumerations/containernetworkingmode.md本文主体与 cpp/enumerations/index.mdC# 枚举参考csharp/enumerations/containernetworkingmode.mdC 枚举参考c/enumerations/wslccontainernetworkingmode.md对应的设置函数为 WslcSetContainerSettingsNetworkingModeC 设置类参考cpp/settings-classes/containersettings.md含完整初始化示例底层实现与测试wslcsdk.idl、ContainerSettings.cpp、wslcsdk.h、WslcSdkWinRTTests.cpp小结与选择建议需要对外提供网络服务、配合PortMappings暴露端口时选择Bridged值1追求网络隔离、无需外部访问时选择None值0枚举只接受这两个值其他数值一律在属性 setter 处以E_INVALIDARG拒绝容器初始化后不可再修改端口映射仅在Bridged模式下合法None模式下配置端口映射会在CreateContainer阶段直接失败。【免费下载链接】WSLWindows Subsystem for Linux项目地址: https://gitcode.com/GitHub_Trending/ws/WSL创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考