企业官网建设流程全解析

• 前端
• 构建工具

本文基于 node-sass 仓库内 LibSass 子项目的官方文档 build-with-visual-studio.md 编写，系统讲解如何在 Windows 上构建 LibSass C 语言库：从环境要求（Visual Studio 2013+、git）、解决方案构建、静态库开关LIBSASS_STATIC_LIB，到命令提示符与 PowerShell 下的 MSBuild 命令行构建。读完后你既能独立完成libsass.dll/libsass.lib的编译，也能理解项目文件中版本探测、导出宏定义等底层机制。

一、构建前须知：环境与版本探测

最低环境要求

根据 构建文档 的明确要求：

• 构建 LibSass 的最低要求是Visual Studio 2013 Express for Desktop；
• 建议安装git并将其加入PATH，用于推导 LibSass 的版本信息。例如，如果安装了 GitHub for Windows，PATH中会出现形如X:\Users\<YOUR_NAME>\AppData\Local\GitHub\PortableGit_<SOME_GUID>\cmd\的条目（其中X是系统盘盘符）。

没有 git 时会发生什么：版本为[NA]

文档指出，如果git不可用，查询 LibSass 版本的结果将是[NA]。这个行为可以直接在工程文件中得到印证：libsass.vcxproj 的开头定义了版本属性与版本探测目标：

<PropertyGroup> <LIBSASS_VERSION>[NA]</LIBSASS_VERSION> <LIBSASS_SRC_DIR>..\src</LIBSASS_SRC_DIR> <LIBSASS_HEADERS_DIR>..\src</LIBSASS_HEADERS_DIR> <LIBSASS_INCLUDES_DIR>..\include</LIBSASS_INCLUDES_DIR> </PropertyGroup> <Target Name="GitVersion"> <Exec Command="git -C .. describe --abbrev=4 --dirty --always --tags" LogStandardErrorAsError="true" ContinueOnError="true" ConsoleToMSBuild="true"> <Output TaskParameter="ConsoleOutput" PropertyName="LIBSASS_VERSION" /> </Exec> </Target>

关键细节：

• LIBSASS_VERSION的默认值就是[NA]，只有GitVersion目标成功执行git describe --abbrev=4 --dirty --always --tags后才会被覆盖为真实的 tag 描述；
• Exec任务带有ContinueOnError="true"，因此在无 git 的机器上构建不会失败，只是静默回退到[NA]；
• libsass.sln的DefaultTargets="GitVersion;Main"说明每次构建都会先跑版本探测、再进入Main目标。

探测到的版本号最终通过VersionMacros目标注入预处理器宏LIBSASS_VERSION，配合头文件 version.h.in 使用：

#ifndef LIBSASS_VERSION #define LIBSASS_VERSION "@PACKAGE_VERSION@" #endif #ifndef LIBSASS_LANGUAGE_VERSION #define LIBSASS_LANGUAGE_VERSION "3.5" #endif

也就是说：宏LIBSASS_VERSION若由 MSBuild 注入则以注入值为准，否则回退到构建系统生成的@PACKAGE_VERSION@；而LIBSASS_LANGUAGE_VERSION固定为"3.5"，表示 LibSass 实现的 Sass 语言版本。

二、解决方案结构：为什么构建前值得先了解这几个文件

LibSass 在 Windows 上的构建文件都位于 src/libsass/win 目录：

文档中提到的“Visual Studio will form the filtered source tree as shown below”，对应的就是 filters 文件中的四个过滤器：

• Header Files（Headers）包含.h与.hpp文件（如ast.hpp、parser.hpp）；
• Source Files（Sources）覆盖.c与.cpp文件（如sass.cpp、cencode.c）；
• 其余被引用的头文件/源码（例如标准库与 SDK 头文件）会出现在External Dependencies下。

filters 文件还专门列出了对外发布的公共头文件，即include目录下的sass.h、sass2scss.h、sass/base.h、sass/context.h、sass/functions.h、sass/values.h、sass/version.h（见 libsass.targets 的 “LibSass Include Headers” 分组）。

排错提示（继承自原文档）：如果有 LibSass 的源码文件错误地出现在 External Dependencies 下，可以修改 libsass.vcxproj.filters 文件，或者直接在解决方案资源管理器中拖拽修正分组。

三、在 Visual Studio 中构建

构建动态库 libsass.dll

打开win\libsass.sln解决方案，按Ctrl+Shift+B构建，即得到libsass.dll。

构建静态库 libsass.lib

原文档建议：在启动工程前设置环境变量LIBSASS_STATIC_LIB：

cd path\to\libsass SET LIBSASS_STATIC_LIB=1 :: :: or in PowerShell: :: $env:LIBSASS_STATIC_LIB=1 :: win\libsass.sln

这个开关在 libsass.vcxproj 中的实现非常简洁：

<PropertyGroup Condition="$(LIBSASS_STATIC_LIB) == ''"> <ConfigurationType>DynamicLibrary</ConfigurationType> <PreprocessorDefinitions>ADD_EXPORTS;$(PreprocessorDefinitions);</PreprocessorDefinitions> </PropertyGroup> <PropertyGroup Condition="$(LIBSASS_STATIC_LIB) != ''"> <ConfigurationType>StaticLibrary</ConfigurationType> </PropertyGroup>

也就是说：

• 变量为空 →ConfigurationType为DynamicLibrary，并自动附加预处理器定义ADD_EXPORTS（这是 DLL 导出符号所必需的）；
• 变量非空 →ConfigurationType为StaticLibrary，产物为libsass.lib。

ADD_EXPORTS的作用在公共头文件 sass/base.h 中定义：

#ifdef _WIN32 /* You should define ADD_EXPORTS *only* when building the DLL. */ #ifdef ADD_EXPORTS #define ADDAPI __declspec(dllexport) #define ADDCALL __cdecl #else #define ADDAPI #define ADDCALL #endif #else #define ADDAPI #define ADDCALL #endif

在 Windows 上，只有定义ADD_EXPORTS时ADDAPI才展开为__declspec(dllexport)，从而让 C API（sass.h、sass2scss.h中的函数）被导出到 DLL；静态库使用者与 DLL 消费者看到的ADDAPI则是空宏。工程文件中的注释也呼应了这一点：“You should define ADD_EXPORTSonlywhen building the DLL”。

构建输出位置同样在工程文件中可见（libsass.vcxproj）：

• Debug 配置：$(SolutionDir)bin\Debug\（中间文件在bin\Debug\obj\）；
• Release 配置：$(SolutionDir)bin\（中间文件在bin\obj\）。

即libsass.dll/libsass.lib会落在src/libsass/win/bin目录（Debug 下多一层Debug子目录）。

四、从命令提示符（cmd）构建

原文档对命令行构建给出两条注意事项，必须原样遵守：

• 如果平台是32 位 Windows，请将命令中的ProgramFiles(x86)替换为ProgramFiles；
• 如果使用Visual Studio 2015构建，请将12.0替换为14.0。

构建动态库 libsass.dll

:: debug build: "%ProgramFiles(x86)%\MSBuild\12.0\Bin\MSBuild" win\libsass.sln :: release build: "%ProgramFiles(x86)%\MSBuild\12.0\Bin\MSBuild" win\libsass.sln ^ /p:Configuration=Release

构建静态库 libsass.lib

:: debug build: "%ProgramFiles(x86)%\MSBuild\12.0\Bin\MSBuild" win\libsass.sln ^ /p:LIBSASS_STATIC_LIB=1 :: release build: "%ProgramFiles(x86)%\MSBuild\12.0\Bin\MSBuild" win\libsass.sln ^ /p:LIBSASS_STATIC_LIB=1 /p:Configuration=Release

注意 cmd 中使用^作为续行符；/p:全局属性与“先设置环境变量再打开解决方案”的方式等价，因为 MSBuild 会优先使用命令行传入的/p:属性。

五、从 PowerShell 构建

构建动态库 libsass.dll

# debug build: &"${env:ProgramFiles(x86)}\MSBuild\12.0\Bin\MSBuild" win\libsass.sln # release build: &"${env:ProgramFiles(x86)}\MSBuild\12.0\Bin\MSBuild" win\libsass.sln ` /p:Configuration=Release

构建静态库 libsass.lib

# build: &"${env:ProgramFiles(x86)}\MSBuild\12.0\Bin\MSBuild" win\libsass.sln ` /p:LIBSASS_STATIC_LIB=1 # release build: &"${env:ProgramFiles(x86)}\MSBuild\12.0\Bin\MSBuild" win\libsass.sln ` /p:LIBSASS_STATIC_LIB=1 /p:Configuration=Release

注意 PowerShell 中续行符是反引号`，且需要用&调用操作符执行带引号的可执行文件路径，这两点与 cmd 的写法差异最容易被忽略。

六、构建机制纵深解析

1. 版本宏注入链路

结合 libsass.vcxproj 可以看到完整的构建顺序：Main目标先打印libsass: $(LIBSASS_VERSION)以及Building Static/Dynamic LibSass（用于确认LIBSASS_STATIC_LIB是否生效），随后依次调用VersionMacros与Build。VersionMacros通过给ClCompile项追加LIBSASS_VERSION="$(LIBSASS_VERSION)"预处理器定义完成注入。因此构建输出中会明确显示当前正在构建的版本号或[NA]，是快速验证 git 探测是否成功的手段。

2. 工具集与条件编译

工程文件按 Visual Studio 版本选择工具集（libsass.vcxproj）：

<PropertyGroup Label="VS2013 toolset selection" Condition="'$(VisualStudioVersion)' == '12.0'"> <PlatformToolset>v120</PlatformToolset> </PropertyGroup> <PropertyGroup Label="VS2015 toolset selection" Condition="'$(VisualStudioVersion)' == '14.0'"> <PlatformToolset>v140</PlatformToolset> </PropertyGroup>

这与文档“VS2015 请将 12.0 换成 14.0”的说明一致：MSBuild 路径中的12.0/14.0对应 VS2013/VS2015 的构建工具目录，而工程内部按VisualStudioVersion匹配v120/v140工具集。此外，libsass.targets 中有一个条件编译项：

<ClCompile Condition="$(VisualStudioVersion) &lt; 14.0" Include="$(LIBSASS_SRC_DIR)\c99func.c" />

即仅在使用 VS2013 工具集时才编译c99func.c（为较旧的 MSVC 提供 C99 风格函数兼容），VS2015 及以上自动跳过。Release 配置还开启了/GL级别的整程序优化（WholeProgramOptimization）与 COMDAT 折叠、引用优化等链接设置。

3. 公共头文件与包含路径

工程把..\include加入AdditionalIncludeDirectories，因此下游项目只需链接libsass.lib或libsass.dll并把src/libsass/include目录（相对本仓库即 src/libsass/include）加入包含路径，即可使用sass.h、sass2scss.h等 C API 头文件。

七、与 node-sass 整体构建体系的关系

需要区分两条构建路径：

1. Windows 解决方案路径（本文主题）：src/libsass/win/libsass.sln用于独立开发、调试与打包 LibSass C 库本身，产物是libsass.dll/libsass.lib；
2. node-sass 的 node-gyp 路径：node-sass 自身通过 binding.gyp 与 src/libsass.gyp 编译 libsass 源码，产出binding.node供 Node.js 加载（见 lib/binding.js 的加载逻辑）。仓库根目录的 appveyor.yml 展示了 CI 上这条路径的配置：使用GYP_MSVS_VERSION=2019、Visual Studio 2019 镜像，配合npm install在 Windows 上构建 Node 绑定。

因此，如果你要调试 libsass 的 C++ 内部实现、验证导出符号或制作独立 DLL，用本文的 VS 方案；如果你只是要在 Windows 上安装/构建 node-sass 扩展，则走 node-gyp 流程即可，无需打开libsass.sln。

八、常见问题速查

以上所有命令与配置均以当前仓库 src/libsass/win 目录下的实际工程文件为准；若使用更新版本的 Visual Studio，请按“32 位换ProgramFiles、14.0 对应 VS2015”同样的规则推导 MSBuild 安装路径与版本号。

• 前端
• 构建工具