如何在Node.js（Express后端）中判断Azure文件存储中的文件是否存在（无需下载完整文件）

My Scenario #

I'm using Azure File Storage with an Express.js backend to render content stored in the storage. I've implemented code based on the official Azure SDK docs to download and read files, but I only need to check if a file exists—downloading the entire file is a waste of time and resources. I looked through the docs for the File Client class but couldn't find a direct method for this. How can I achieve this efficiently?

My current code setup (relevant parts):

const { ShareServiceClient, StorageSharedKeyCredential } = require("@azure/storage-file-share");
const account = "<account>";
const accountKey = "<accountkey>";
const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);
const shareName = "<share name>";
const fileName = "<file name>";

// Helper to convert stream to buffer (for downloading files)
async function streamToBuffer(readableStream) {
  return new Promise((resolve, reject) => {
    const chunks = [];
    readableStream.on("data", (data) => {
      chunks.push(data instanceof Buffer ? data : Buffer.from(data));
    });
    readableStream.on("end", () => {
      resolve(Buffer.concat(chunks));
    });
    readableStream.on("error", reject);
  });
}

// Current way to read file content (not what I need)
// const downloadFileResponse = await fileClient.download();
// const output = await streamToBuffer(downloadFileResponse.readableStreamBody)).toString()

Solution: Use getFileClient().getProperties() #

Great question—avoiding full file downloads for existence checks is a smart move for performance, especially with large files. The trick is to use the getProperties() method on the FileClient object. This method sends a HEAD request to Azure File Storage, which only retrieves the file's metadata (like size, creation date) instead of the actual content.

Here's how to implement it in your code:

Step-by-Step Code Example #

async function checkFileExists() {
  // 1. Get the client for your target share
  const shareClient = serviceClient.getShareClient(shareName);
  
  // 2. Get the directory client (use root directory if your file isn't in a subfolder)
  // If your file is in a subdirectory, use getDirectoryClient("<subdir-name>") instead
  const directoryClient = shareClient.getRootDirectoryClient();
  
  // 3. Get the client for your specific file
  const fileClient = directoryClient.getFileClient(fileName);

  try {
    // 4. Request file properties—no content is downloaded
    await fileClient.getProperties();
    console.log(`File "${fileName}" exists in share "${shareName}"`);
    return true;
  } catch (error) {
    // 5. Handle the "Not Found" case (status code 404)
    if (error.statusCode === 404) {
      console.log(`File "${fileName}" does NOT exist in share "${shareName}"`);
      return false;
    } else {
      // Handle other potential errors (e.g., permission issues, network failures)
      console.error("Unexpected error checking file existence:", error);
      throw error; // Re-throw if you want upstream code to handle it
    }
  }
}

// Usage in your Express route or backend logic
// app.get('/check-file', async (req, res) => {
//   const exists = await checkFileExists();
//   res.json({ exists });
// });

Why This Works #

• getProperties() triggers a lightweight HEAD request, which is far faster than downloading the entire file.
• If the file exists, the method resolves successfully with the file's metadata.
• If the file doesn't exist, Azure returns a 404 status code, which the SDK wraps in an error—we catch this to confirm the file is missing.

Notes #

• If your file is stored in a subdirectory, replace getRootDirectoryClient() with getDirectoryClient("<your-subdirectory-path>") (e.g., getDirectoryClient("docs/reports")).
• Make sure your storage account credentials have the Read permission for the target share/file—otherwise, you'll get a 403 (Forbidden) error instead of 404.

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