新建VC2019项目并集成 WebView2 完整流程

新建VC2019项目并集成 WebView2 完整流程

从零创建 AoUnitDone MFC 对话框项目、集成 WebView2、加载指定网页完整步骤,覆盖常见坑:Callback 找不到、ResizeWebView 未声明、Release 链接错误、字符集错误、DLL 缺失。

一、创建 MFC 对话框项目

  1. VS2019 → 文件 → 新建 → 项目 → MFC 应用程序
  2. 项目名:AoUnitDone,存储位置自定义
  3. 应用程序类型选择:基于对话框,其余默认,点击完成
  4. 项目属性配置
    • C/C++ → 语言 → C++ 语言标准:ISO C++ 17
    • 配置属性 → 高级 → 字符集:保持 使用 Unicode 字符集(默认)

二、NuGet 安装 WebView2 与 WIL

右键项目 → 管理 NuGet 程序包 → 浏览,依次安装下面两个包:

表格

包名 版本建议
Microsoft.Web.WebView2 最新稳定版(如 1.0.4191.47 或更新)
Microsoft.Windows.ImplementationLibrary 最新稳定版

安装完成后 packages.config 会生成对应条目,packages\ 目录自动生成。

三、静态链接 WebView2Loader(解决 Release 缺 DLL)

  1. 在 VS 解决方案资源管理器右键项目 → 卸载项目
  2. 右键项目 → 编辑 AoUnitDone.vcxproj
  3. 找到 <ImportGroup> 节点,在节点后方添加下面配置:
<PropertyGroup Label="Globals">
  <VCProjectVersion>16.0</VCProjectVersion>
  <Keyword>Win32Proj</Keyword>
  <ProjectGuid>...</ProjectGuid>
  <RootNamespace>AoUnitDone</RootNamespace>
  <WindowsTargetPlatformVersion>10.0</WindowsTargetPlatformVersion>
  <!-- 加这一行:静态链接 WebView2 Loader -->
  <WebView2LoaderPreference>Static</WebView2LoaderPreference>
</PropertyGroup>
  1. 保存文件,右键项目 → 重新加载项目

效果:Debug/Release 都会将 Loader 静态链入 EXE,不再依赖 WebView2Loader.dll。

四、初始化 COM(App 类 AoUnitDone.cpp)

修改 InitInstance() 和 ExitInstance(),WebView2 需要 STA 单元。

BOOL CAoUnitDoneApp::InitInstance()
{
    // WebView2 要求 STA
    HRESULT hr = CoInitializeEx(nullptr, COINIT_APARTMENTTHREADED | COINIT_DISABLE_OLE1DDE);
    if (FAILED(hr)) return FALSE;
    CWinApp::InitInstance();
    // ... 原有初始化代码保持不变 ...
    return TRUE;
}

int CAoUnitDoneApp::ExitInstance()
{
    CoUninitialize();
    return CWinApp::ExitInstance();
}

注意:如果代码中已有 AfxOleInit(),其内部已经执行 CoInitializeEx,可以保留,二者引用计数会自动平衡。

五、对话框头文件声明 AoUnitDoneDlg.h

文件顶部增加头文件,在对话框类中增加成员变量与函数声明

/*/在 pch.h 里统一包含(只编译一次)
#ifndef PCH_H
#define PCH_H
#include "framework.h"
#include <WebView2.h>
#include <wrl.h>
#include <wil/com.h>
using namespace Microsoft::WRL;
#endif //PCH_H
*/



class CAoUnitDoneDlg : public CDialogEx
{
    // ... 原有 DECLARE_MESSAGE_MAP 等内容 ...
private:
    wil::com_ptr<ICoreWebView2Controller> m_webViewController;
    wil::com_ptr<ICoreWebView2>           m_webView;
    void ResizeWebView();
public:
    afx_msg void OnSize(UINT nType, int cx, int cy);
    DECLARE_MESSAGE_MAP()
};

关键点说明

  • #include <wrl.h>:提供 Microsoft::WRL::Callback
  • #include <wil/com.h>:提供 wil::com_ptr
  • #include <WebView2.h>:NuGet 自动配置包含目录
  • ResizeWebView()必须头文件声明,否则调用报 C3861 未找到标识符

六、对话框源文件实现 AoUnitDoneDlg.cpp

6.1 文件顶部引入头文件

//在 pch.h 里统一包含

6.2 消息映射增加 ON_WM_SIZE

BEGIN_MESSAGE_MAP(CAoUnitDoneDlg, CDialogEx)
    ON_WM_SYSCOMMAND()
    ON_WM_PAINT()
    ON_WM_QUERYDRAGICON()
    ON_WM_SIZE()                        // ★ 新增窗口大小变化消息
END_MESSAGE_MAP()

6.3 OnInitDialog 初始化 WebView2

BOOL CAoUnitDoneDlg::OnInitDialog()
{
    CDialogEx::OnInitDialog();
    // 取系统临时目录,拼出用户数据文件夹路径
    TCHAR szTemp[MAX_PATH] = { 0 };
    ::GetTempPath(MAX_PATH, szTemp);
    CString strUserData(szTemp);
    strUserData += _T("AoUnitDone.exe.WebView2");
    HWND hWnd = GetSafeHwnd();

    // 4 个参数:browserExecutableFolder / userDataFolder / options / handler
    HRESULT hr = CreateCoreWebView2EnvironmentWithOptions(
        nullptr,          // browserExecutableFolder,nullptr 使用系统已装 Runtime
        strUserData,      // userDataFolder,CString 可隐式转 LPCWSTR
        nullptr,          // environmentOptions
        Callback<ICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler>(
            [hWnd, this](HRESULT result, ICoreWebView2Environment* env) -> HRESULT
            {
                if (FAILED(result) || env == nullptr)
                    return result;
                // 2 个参数:parentWindow / handler
                return env->CreateCoreWebView2Controller(
                    hWnd,
                    Callback<ICoreWebView2CreateCoreWebView2ControllerCompletedHandler>(
                        [this](HRESULT result, ICoreWebView2Controller* controller) -> HRESULT
                        {
                            if (FAILED(result) || controller == nullptr)
                                return result;
                            m_webViewController = controller;
                            controller->get_CoreWebView2(&m_webView);
                            ResizeWebView();
                            // Navigate必须在回调内部,此时m_webView才有效
                            m_webView->Navigate(L"https://www.kdocs.cn/l/cbAN1JHfVpW2");
                            return S_OK;
                        }).Get());
            }).Get());
    return TRUE;
}

6.4 ResizeWebView 和 OnSize 窗口自适应

void CAoUnitDoneDlg::ResizeWebView()
{
    if (m_webViewController != nullptr)
    {
        CRect rectClient;
        GetClientRect(&rectClient);
        m_webViewController->put_Bounds(rectClient);
    }
}

void CAoUnitDoneDlg::OnSize(UINT nType, int cx, int cy)
{
    CDialogEx::OnSize(nType, cx, cy);
    ResizeWebView();
}

七、编译与运行

7.1 Debug 编译

直接:生成 → 重新生成解决方案。

7.2 Release 编译遇到 LNK2005 重复定义错误

报错示例:error LNK2005: "wistd::weak_ordering ..." 已经在 xxx.obj 中定义

按顺序尝试下面方案: 方案 A(推荐)

  1. 链接器 → 输入 → 附加依赖项,最前面添加:
nafxcw.lib;libcmt.lib
  1. 链接器 → 输入 → 忽略特定默认库添加:
nafxcw.lib

方案 B 链接器 → 命令行 → 其他选项添加:

/FORCE:MULTIPLE

方案 C 升级 Microsoft.Web.WebView2 和 WIL 到最新稳定版本,重新生成。

7.3 运行环境

  1. 目标机器需要安装 WebView2 Runtime;开发机安装 Edge 浏览器一般自带 Runtime。
  2. 弹窗提示未安装 WebView2 Runtime:去微软官网下载 Evergreen Bootstrapper 安装。
  3. 运行效果:对话框客户区渲染网页,拖动窗口大小网页跟随自适应缩放。