求助：Netlify构建TypeScript无服务器应用时libpq/gyp错误的其他排查方法

问题背景 #

基于TypeScript的无服务器应用本地使用netlify dev运行正常，可连接Railway上的Postgres数据库，但部署至Netlify时持续出现libpq和gyp相关构建错误。

已尝试的无效方案 #

• 删除package-lock.json与node_modules后重新执行npm i
• 安装postgresql-dev依赖
• 将Netlify上的Node版本设置为14.17.5

目前怀疑问题可能与TypeScript有关（非TypeScript项目可正常部署），现寻求其他可行的排查与解决方法。

构建失败日志 #

6:52:23 PM: Build ready to start
6:52:25 PM: build-image version: 9289b698a503f132b265bd089ab40ce1d6f9e65e (focal)
6:52:25 PM: build-image tag: v4.12.0
6:52:25 PM: buildbot version: c87074660cd9a4568c0ac759bc083987e94204b3
6:52:26 PM: Fetching cached dependencies
6:52:26 PM: Starting to download cache of 2.3KB
6:52:26 PM: Finished downloading cache in 52.739394ms
6:52:26 PM: Starting to extract cache
6:52:26 PM: Finished extracting cache in 3.09226ms
6:52:26 PM: Finished fetching cache in 121.710237ms
6:52:26 PM: Starting to prepare the repo for build
6:52:26 PM: Preparing Git Reference refs/heads/main
6:52:26 PM: Parsing package.json dependencies
6:52:27 PM: Different functions path detected, going to use the one specified in the Netlify configuration file: 'functions' versus '' in the Netlify UI
6:52:27 PM: Starting build script
6:52:27 PM: Installing dependencies
6:52:27 PM: Python version set to 2.7
6:52:28 PM: Downloading and installing node v14.17.5...
6:52:28 PM: Downloading https://nodejs.org/dist/v14.17.5/node-v14.17.5-linux-x64.tar.xz...
6:52:28 PM: Computing checksum with sha256sum
6:52:28 PM: Checksums matched!
6:52:30 PM: Now using node v14.17.5 (npm v6.14.14)
6:52:30 PM: Started restoring cached build plugins
6:52:30 PM: Finished restoring cached build plugins
6:52:30 PM: Attempting ruby version 2.7.2, read from environment
6:52:30 PM: Using ruby version 2.7.2
6:52:31 PM: Using PHP version 8.0
6:52:31 PM: No npm workspaces detected
6:52:31 PM: Started restoring cached node modules
6:52:31 PM: Finished restoring cached node modules
6:52:31 PM: Installing NPM modules using NPM version 6.14.14
6:52:36 PM: > libpq@1.8.12 install /opt/build/repo/node_modules/libpq
6:52:36 PM: > node-gyp rebuild
6:52:39 PM: find: ‘/usr/pg*’: No such file or directory
6:52:39 PM: gyp: Call to 'which pg_config || find /usr/bin /usr/local/bin /usr/pg* /opt -executable -name pg_config -print -quit' returned exit status 1 while in binding.gyp. while trying to load binding.gyp
6:52:39 PM: gyp ERR! configure error
6:52:39 PM: gyp ERR! stack Error: `gyp` failed with exit code: 1
6:52:39 PM: gyp ERR! stack     at ChildProcess.onCpExit (/opt/buildhome/.nvm/versions/node/v14.17.5/lib/node_modules/npm/node_modules/node-gyp/lib/configure.js:351:16)
6:52:39 PM: gyp ERR! stack     at ChildProcess.emit (events.js:400:28)
6:52:39 PM: gyp ERR! stack     at Process.ChildProcess._handle.onexit (internal/child_process.js:277:12)
6:52:39 PM: gyp ERR! System Linux 5.4.196-108.356.amzn2.x86_64
6:52:39 PM: gyp ERR! command "/opt/buildhome/.nvm/versions/node/v14.17.5/bin/node" "/opt/buildhome/.nvm/versions/node/v14.17.5/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js" "rebuild"
6:52:39 PM: gyp ERR! cwd /opt/build/repo/node_modules/libpq
6:52:39 PM: gyp ERR! node -v v14.17.5
6:52:39 PM: gyp ERR! node-gyp -v v5.1.0
6:52:39 PM: gyp ERR! not ok
6:52:39 PM: npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@2.3.2 (node_modules/fsevents):
6:52:39 PM: npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for fsevents@2.3.2: wanted {"os":"darwin","arch":"any"} (current: {"os":"linux","arch":"x64"})
6:52:39 PM: npm ERR! code ELIFECYCLE
6:52:39 PM: npm ERR! errno 1
6:52:39 PM: npm ERR! libpq@1.8.12 install: `node-gyp rebuild`
6:52:39 PM: npm ERR! Exit status 1
6:52:39 PM: npm ERR!
6:52:39 PM: npm ERR! Failed at the libpq@1.8.12 install script.
6:52:39 PM: npm ERR! This is probably not a problem with npm. There is likely additional logging output above.
6:52:39 PM: npm ERR! A complete log of this run can be found in:
6:52:39 PM: npm ERR!     /opt/buildhome/.npm/_logs/2022-10-11T01_52_39_917Z-debug.log
6:52:39 PM: Error during NPM install
6:52:39 PM: Build was terminated: Build script returned non-zero exit code: 1
6:52:39 PM: Creating deploy upload records
6:52:40 PM: Failing build: Failed to build site
6:52:40 PM: Failed during stage 'building site': Build script returned non-zero exit code: 1
6:52:40 PM: Finished processing build request in 14.377988447s

可行排查与解决方法 #

1. 替换原生libpq依赖为纯JS驱动 #

libpq是原生C++依赖，需要在构建环境编译，Netlify默认环境缺少相关编译依赖。换成无需编译的纯JS Postgres驱动可规避此问题：

• 卸载现有libpq：npm uninstall libpq
• 安装纯JS驱动（二选一）：
  • npm install pg（Node生态常用驱动）
  • npm install postgres（轻量现代驱动）
• 调整代码中的数据库连接逻辑，适配新驱动的API

2. 在Netlify构建环境安装PostgreSQL依赖 #

若必须保留libpq，需在构建前手动安装PostgreSQL客户端工具，让pg_config可被找到：

• 在项目根目录的netlify.toml中添加构建命令配置：

[build]
  command = "apt-get update && apt-get install -y postgresql-client && npm run build"

或直接在Netlify后台的「构建设置」里，将构建命令修改为上述内容。

3. 禁用Netlify构建缓存 #

Netlify的依赖缓存可能保留了损坏的libpq编译产物，禁用缓存后重新构建：

• 进入Netlify后台，找到对应站点的「Build & deploy」→「Post processing」
• 勾选「Disable build cache」，然后手动触发一次新构建

4. 升级node-gyp版本 #

日志中node-gyp版本为v5.1.0，较老版本与Node 14可能存在兼容性问题，强制升级：

• 安装依赖：npm install npm-force-resolutions --save-dev
• 在package.json中添加配置：

"resolutions": {
  "node-gyp": "^9.0.0"
},
"scripts": {
  "preinstall": "npx npm-force-resolutions"
}

• 重新执行npm i后再部署

5. 验证TypeScript编译配置 #

确认TypeScript编译后的产物符合Netlify函数要求：

• 检查tsconfig.json的outDir是否指向Netlify函数目录（如./functions）
• 本地执行npm run build，确认编译后的JS文件生成在正确位置，且可正常运行
• 确保Netlify构建命令包含TypeScript编译步骤（如tsc && npm run build:functions）

内容的提问来源于stack exchange，提问作者Asa LeHolland