如何在JavaScript中编译时导入.cypher文件运行Neo4j查询

核心实现逻辑是在构建/模块编译阶段将独立存储的.cypher文件内容内联为JavaScript字符串，运行时无任何文件IO开销，和硬编码字符串的执行效率完全一致，同时可以把Cypher语句维护在独立文件中，避免硬编码带来的转义错误、语句拼接错误问题。

根据你使用的技术栈，选择对应配置即可：

Vite 项目（前端/Node.js ESM 通用） #

Vite 原生支持文本资源导入，零额外依赖：

• TypeScript 项目先在全局类型声明文件（如vite-env.d.ts）中添加模块类型定义，纯JS项目可跳过这步：

declare module '*.cypher' {
  const cypherContent: string;
  export default cypherContent;
}

• 直接在代码中导入.cypher文件即可使用，若遇到解析报错，在导入路径后加?raw后缀强制指定为文本资源导入：

// 导入.cypher文件，拿到的就是纯Cypher语句字符串
import queryUser from './cypher/queryUser.cypher?raw'

// 直接传给Neo4j driver使用，和硬编码参数用法完全一致
const res = await session.run(queryUser, { uid: '1001' })

Webpack 项目 #

Webpack 5.x 内置静态资源处理能力，无需安装旧版raw-loader：

• 在webpack.config.js中添加文件解析规则：

module.exports = {
  module: {
    rules: [
      {
        test: /\.cypher$/,
        type: 'asset/source'
      }
    ]
  }
}

• 添加上述TS类型声明后，即可直接import .cypher文件使用。Webpack 4及更早版本安装raw-loader配置对应规则即可，逻辑完全相同。

无构建工具的原生Node.js ESM环境 #

Node.js 20+ 支持自定义ESM Loader，可在模块加载阶段直接解析.cypher文件，无需提前构建：

• 新建cypher-loader.mjs文件：

export async function load(url, context, nextLoad) {
  if (url.endsWith('.cypher')) {
    const { readFile } = await import('node:fs/promises')
    const source = await readFile(new URL(url), 'utf8')
    return {
      format: 'module',
      source: `export default ${JSON.stringify(source)}`,
      shortCircuit: true
    }
  }
  return nextLoad(url, context)
}

• 启动服务时附加loader参数即可：

node --experimental-loader ./cypher-loader.mjs app.js

该方案的文件读取仅发生在服务启动的模块编译阶段，运行时执行查询不会产生任何额外IO开销。

纯TypeScript（tsc编译）无构建工具场景 #

直接用tsc编译TS代码时，可通过预编译脚本批量将.cypher文件转换为可导入的JS模块，该步骤仅在编译阶段执行一次：

• 在package.json中添加预构建脚本：

{
  "scripts": {
    "prebuild": "node scripts/transform-cypher.js",
    "build": "tsc"
  }
}

• transform-cypher.js的逻辑为遍历项目中所有.cypher文件，在同目录生成对应的.cypher.js文件，内容为转义后的字符串导出语句，例如export default "MATCH (n:User) WHERE n.id = $uid RETURN n"。添加对应的TS类型声明后，即可正常导入使用。

注意：所有方案导入的Cypher语句都是静态字符串，不存在运行时解析开销，传入Neo4j driver的方式和硬编码完全一致，不需要做额外处理。

内容的提问来源于stack exchange，提问作者Mike M