PAYATHON 2026

HTML/CSS/JS 与 C++/Wasm 项目如何组织目录,是否需要 CMake?

数据阿明

现有目录可以作为起点。对于多人协作、计算核心由 C++ 实现的项目,建议将前端源码、C++ 核心、Wasm 接口层和构建产物放在不同目录,并用 CMake 管理 C++ 到 Wasm 的构建。CMake 不是必需的;源文件较少时,也可以直接运行 em++。

这里的 C++ 模块仍运行在浏览器中,项目不需要因为使用 C++ 就额外划分出服务端。

目录应该怎样组织?

可以采用下面的结构,具体名称由团队统一即可:

project/
├── CMakeLists.txt
├── cpp/
│   ├── include/
│   │   └── core.hpp
│   ├── src/
│   │   └── core.cpp
│   └── wasm/
│       └── bindings.cpp
├── web/
│   ├── index.html
│   ├── css/
│   ├── js/
│   │   ├── app.js
│   │   └── wasm-client.js
│   └── assets/
├── tests/
├── build/
├── .gitignore
└── README.md

各目录的职责是:

  • cpp/include/:计算核心对外提供的头文件;只在内部使用的头文件也可以放在 cpp/src/。
  • cpp/src/:计算逻辑,尽量不依赖 DOM 或浏览器交互。
  • cpp/wasm/:向 JavaScript 暴露的接口,以及必要的数据转换。
  • web/:手写的 HTML、CSS、JavaScript 和静态资源。
  • web/js/wasm-client.js:集中处理模块初始化和调用,向 UI 提供普通 JavaScript 函数。
  • build/:CMake 缓存、目标文件和生成的站点文件,通常不提交到版本库。

也可以保留原来位于根目录的 include/ 和 src/。把它们收进 cpp/,主要是为了方便浏览混合语言项目。src/lib/ 建议按具体功能命名;如果存放第三方依赖,应明确区分其来源和管理方式。

对于没有前端构建工具的项目,原来的 public/ 可以继续承担 web/ 的职责。如果以后引入前端工具,应按该工具对 public/ 的约定安排文件。

CMake 负责哪部分构建?

CMake 适合管理 C++ 源文件、头文件路径、依赖库和链接参数;Emscripten 提供编译到 Wasm 的工具链。官方支持通过 emcmake cmake 配置项目,再使用 cmake --build 构建,参见 Emscripten 构建文档。

普通 HTML、CSS 和 JavaScript 可以直接复制到站点输出目录。如果后续需要 JavaScript 打包或 CSS 处理,再增加相应的前端构建步骤即可。

建议将计算核心定义为独立的 CMake target,再让 Wasm 接口 target 链接它。后续添加原生 C++ 测试时,也能复用核心代码。

一个最小的 CMake 与接口示例

下面用“计算平方”演示文件之间的关系,实际项目应替换为自己的计算接口。示例使用 CMake 3.13 及以上版本支持的命令,并选择 C++17;这不代表项目必须使用 C++17。

cpp/include/core.hpp:

#pragma once

double calculate(double value);

cpp/src/core.cpp:

#include "core.hpp"

double calculate(double value) {
    return value * value;
}

cpp/wasm/bindings.cpp:

#include "core.hpp"

extern "C" double calculate_value(double value) {
    return calculate(value);
}

extern "C" 避免接口名称被 C++ 名字修饰。链接时还需要导出该函数,JavaScript 才能调用它,参见 Emscripten 的 C/C++ 与 JavaScript 交互说明。

根目录的 CMakeLists.txt:

cmake_minimum_required(VERSION 3.13)
project(browser_compute LANGUAGES CXX)

add_library(core STATIC cpp/src/core.cpp)
target_include_directories(core PUBLIC cpp/include)
target_compile_features(core PUBLIC cxx_std_17)

if(EMSCRIPTEN)
    add_executable(compute cpp/wasm/bindings.cpp)
    target_link_libraries(compute PRIVATE core)

    set_target_properties(compute PROPERTIES
        SUFFIX ".js"
        RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/site/wasm"
    )

    target_link_options(compute PRIVATE
        "--no-entry"
        "-sMODULARIZE=1"
        "-sEXPORT_ES6=1"
        "-sEXPORTED_FUNCTIONS=_calculate_value"
    )
endif()

这个接口没有 main(),因此使用 --no-entry。虽然 CMake 中通过 add_executable 定义了链接目标,产物仍是供浏览器加载的 JavaScript 和 Wasm 文件,不是本机可执行程序。

MODULARIZE 和 EXPORT_ES6 使生成的 JavaScript 提供模块工厂函数,前端等待初始化完成后再调用导出函数。加载方式见 Emscripten 模块化输出说明。

前端如何调用并组织构建产物?

在 web/js/wasm-client.js 中集中初始化模块,并复用同一个初始化 Promise:

import createCompute from '../wasm/compute.js';

const modulePromise = createCompute();

export async function calculateValue(value) {
  if (!Number.isFinite(value)) {
    throw new TypeError('Expected a finite number');
  }

  const module = await modulePromise;
  return module._calculate_value(value);
}

app.js 调用 calculateValue() 并处理结果或异常即可。HTML 入口需要通过 <script type="module"> 加载相应的 JavaScript。

这里的 ../wasm/compute.js 指向构建后的站点目录,源目录 web/ 不必包含生成文件。

假设已经安装并激活 Emscripten,同时安装了 CMake、Ninja 和 Python 3,可以从项目根目录执行:

emcmake cmake -S . -B build/wasm -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build/wasm
cmake -E copy_directory web build/wasm/site
python3 -m http.server 8000 --directory build/wasm/site

然后访问 http://localhost:8000/。示例将前端文件复制到 build/wasm/site/,将 compute.js 和 compute.wasm 放到其中的 wasm/ 目录。修改前端文件后,需要重新执行复制步骤,也可以将复制接入团队的统一构建脚本。

协作时还应约定什么?

先明确跨语言接口的数据类型、错误表示和内存归属。示例只传递一个 double;字符串、数组和 C++ 对象需要额外设计转换方式,不能直接套用这个接口。采用指针和长度传递数据时,还需要明确由谁分配、由谁释放。

生成的 JavaScript 与 Wasm 文件应来自同一次构建,并按加载路径一起部署。通常不应手工修改生成的 compute.js。

如果以后增加本机测试,可以使用 build/native/ 等独立目录,避免与 Emscripten 构建缓存混用。团队还应在 README 中记录工具链版本和构建命令,让新成员能按相同步骤生成站点。

如果计算耗时明显,再评估是否将调用移入 Web Worker。等待 Wasm 初始化的 await 并不会让随后的同步计算自动离开浏览器主线程。

备注:内容仅供参考。