新建VC2019项目并集成 WebView2 完整流程
从零创建 AoUnitDone MFC 对话框项目、集成 WebView2、加载指定网页完整步骤,覆盖常见坑:Callback 找不到、ResizeWebView 未声明、Release 链接错误、字符集错误、DLL 缺失。
一、创建 MFC 对话框项目
- VS2019 → 文件 → 新建 → 项目 → MFC 应用程序
- 项目名:
AoUnitDone,存储位置自定义 - 应用程序类型选择:基于对话框,其余默认,点击完成
- 项目属性配置
- C/C++ → 语言 → C++ 语言标准:
ISO C++ 17 - 配置属性 → 高级 → 字符集:保持 使用 Unicode 字符集(默认)
- C/C++ → 语言 → C++ 语言标准:
二、NuGet 安装 WebView2 与 WIL
右键项目 → 管理 NuGet 程序包 → 浏览,依次安装下面两个包:
表格
| 包名 | 版本建议 |
|---|---|
| Microsoft.Web.WebView2 | 最新稳定版(如 1.0.4191.47 或更新) |
| Microsoft.Windows.ImplementationLibrary | 最新稳定版 |
安装完成后
packages.config会生成对应条目,packages\目录自动生成。
三、静态链接 WebView2Loader(解决 Release 缺 DLL)
- 在 VS 解决方案资源管理器右键项目 → 卸载项目
- 右键项目 → 编辑 AoUnitDone.vcxproj
- 找到
<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>
- 保存文件,右键项目 → 重新加载项目
效果: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(推荐)
- 链接器 → 输入 → 附加依赖项,最前面添加:
nafxcw.lib;libcmt.lib
- 链接器 → 输入 → 忽略特定默认库添加:
nafxcw.lib
方案 B 链接器 → 命令行 → 其他选项添加:
/FORCE:MULTIPLE
方案 C
升级 Microsoft.Web.WebView2 和 WIL 到最新稳定版本,重新生成。
7.3 运行环境
- 目标机器需要安装 WebView2 Runtime;开发机安装 Edge 浏览器一般自带 Runtime。
- 弹窗提示未安装 WebView2 Runtime:去微软官网下载 Evergreen Bootstrapper 安装。
- 运行效果:对话框客户区渲染网页,拖动窗口大小网页跟随自适应缩放。